Data import
General settings
| Setting | Description |
|---|---|
| Name | Type a unique name for the system. Two systems cannot have the same name. |
| System ID | Type a unique System ID for the system. Two systems cannot have the same System ID.You cannot change this setting. |
| Description | Type an optional description of the system. |
| Status | Status of the system. Set the status to Removed to ensure the system is no longer included in warehouse imports, reconciliation, or provisioning. Setting a system as removed will delete all objects referring to the system, including resources, manual and automated provisioning tasks, and assignment policies. |
| Content | The type of content to import. You can choose: Identity data, Access rights, Both (Identity data and access rights) |
| Trusts | Optionally, select one or more trusted systems to associate with the system. |
| Prevent self-service | Optionally, decide if it will be possible or not to request the resource in a self-service requests in that system. |
Trust is specifically designed for use between physical systems. It is not intended for use between logical and physical systems.
Connection details
| Parameter | Description |
|---|---|
| Base URL | This field is optional. You can specify the Base URL of the service. When you specify a Base URL, this URL will be used for all defined queries if these do not specify a full URL of their own. The Base URL should have the following format: https://api.bamboohr.com/api/gateway.php/**Companyname**/v1 (Replace Companyname with the subdomain used by your organization when accessing BambooHR.) |
| Authentication type | Choose the type of authentication to use for theBambooHR system. For BambooHR connectivity, the only supported authentication is Basic (uses Base64-encoded string that contains a username and password) |
| User | Enter the API Key (token) generated earlier. |
| Password | Enter any random password, it is not verified by the BambooHR API. |
| Domain | This field is optional. Here, you can specify the domain name for the user. |
| Headers | This field is optional. Here, you can provide JSON document specifying custom headers. For BambooHR provide the following header: *{"Request":{"Accept": "application/json"}}* |
| Test connection | This field is optional. You can check this field to force the collector to test the defined connection before moving forward. For BambooHR this option is selected by default. |
| Test query | This field only appears if the Test connection field is enabled. Here you can enter an optional test query used to verify the connection. The query must be relative to the base address, for example, Users. For BambooHR the default query employees/directory is supplied automatically. |
Queries and Mappings
Out of the box, the Omada BambooHR Connectivity provides the following mappings.
Identities
Parameters
| Parameter | Value |
|---|---|
| URL | reports/124 |
| Collection | employees |
Mappings
| Destination | Operator | Source |
|---|---|---|
| Business key | Map | id |
| Unique ID | Map | id |
| Name | Map | displayName |
| Status | Expression | status == "" ? "Inactive" : status |
| First name | Map | firstName |
| Last name | Map | lastName |
| Map | workEmail | |
| Job title | Map | jobTitle |
| Country | Map | country |
| Company | Map | company |
| Employee ID | Map | employeeNumber |
| Valid from | Map | hireDate |
| Valid to | Map | terminationDate |
| Type | Constant | Primary |
| Category | Constant | Employee |
| mobilephone | Map | mobilePhone |
| workphone | Map | workPhone |
| department | Map | department |
Identity Owners
Parameters
| Parameter | Value |
|---|---|
| URL | reports/124 |
| Collection | employees |
Mappings
| Destination | Operator | Source |
|---|---|---|
| Owner UID | Map | supervisorEId |
| Identity UID | Map | id |
Contexts
Parameters
| Parameter | Value |
|---|---|
| URL | reports/124 |
| Collection | employees |
| Filter | department+"" != "" |
Mappings
| Destination | Operator | Description |
|---|---|---|
| Business key | Expression | "orgunit_" + department |
| Name | Map | department |
| Type | Constant | OrgUnit |
| Short name | Map | department |
Advanced queries and mappings configuration
If you require any custom mappings for your BambooHR implementation, this section describes the details of the fields available in the Queries task.
This collector supports any number of queries and has the following query parameters which should be specified when creating or editing a query.
- In the URL is a DynamicExpresso expression field, you can specify whether the URL is generated from a DynamicExpresso expression (if Yes is selected) or interpreted directly (if No is selected).
- In the URL, enter the URL for the resource. If No is selected in URL is a DynamicExpresso expression, you can specify a full URL or the part of the URL which should be appended to the Base URL. If Yes is selected in URL as a DynamicExpresso expression, the URL enables the user to specify a DynamicExpresso expression, which is used to generate the URL dynamically.
We recommend to use the SuccessFactors paging mechanisms when querying PerPerson entity to avoid missing or duplicate records. This behavior occurs when the same Entity is updated by another process in parallel while being read from SAP. To enable the paging mechanism to add the paging=snapshot query parameter at the beginning of the URL: PerPerson?paging=snapshot&$filter...
Optionally:
- In the Nested URL root radio button, you can specify whether the return should be the first found collection, by selecting No (which is the default value) or a root element treated as a single element, by selecting Yes.
- Nested URL is root parameter is set to Yes, then the Nested URL Collection must be specified as well, to point to the collection inside the root element from which you want to collect data.
- Disable paging for the Nested URL.
- In the Append, enter some query parameters which should be appended.
- In the Distinct, specify if the collector should remove possible duplicate rows.
- In the Collection, you can specify the name of the collection element in the response from where the result should be read. By default, the result is read from the first found collection.
- In the Description, enter a description for what this query is doing.
- In the Filter, under the Parameters heading, you can provide a Dynamic Expresso expression that is used for filtering the data imported into Omada Identity. It returns a TRUE/FALSE result for each imported data row. If the expression returns FALSE for the given row that row is skipped during import.
The filter can be supplied with special functions #MinRow() or #MaxRow(). The #MinRow()/#MaxRow() are custom functions that can be combined with regular DynamicExpresso expressions thanks to the # prefix. For example, in line:
#MinRow(col1, col2)#col=="active"
The custom function is encapsulated with # at the start and optionally at the end (if a regular filter is to be appended like in the example (col=="active")).
The MinRow()/MaxRow() functions take two parameters. The intention is similar to a Group by function in SQL server that allows you to eliminate duplicates and to take the lowest or highest [order by column] for each [unique column] row, that is, MinRow([unique column], [order by column]).
Example:
MaxRow(UniqueKey, Version)
Input:
| UniqueKey | Version |
|---|---|
| 1 | 1 |
| 1 | 2 |
| 2 | 2 |
| 2 | 1 |
| 3 | 1 |
Output:
| UniqueKey | Version |
|---|---|
| 1 | 2 |
| 2 | 2 |
| 3 | 1 |
Advanced configuration
The Timeout in seconds field allows you to specify how long the collector should wait for a response of the BambooHR service. The default value is set to 3600 seconds (1 hour).
Optionally:
- In the Append URL parameters(s) field, enter any additional query parameters that should be added to any of the queries defined under Queries and Mappings.
- In the Security Protocol drop-down list, choose a security protocol to use for an HTTPS connection, for example, TLS 1.2. Your organization may limit the use of one or more of the default available security protocols.
- In the Paging mechanism field, select the type of paging the service uses. Services may result from large datasets and will return data in chunks. The BambooHR collector offers the following options:
- None: Select this option if the service offers no paging and all data is returned.
- Paging marker: Use this option if the response contains a field with an indicator which should be used in the URL for the subsequent call. If the response is truncated (that is, if it does not contain all the requested objects), it will contain an IsTruncated element set to True and a Marker element, whose value needs to be used as a parameter in the URL of the call for the subsequent page.
- Paging URL: Use this option if the response contains a field with a URL for the next page.
- URL parameters: Use this option if the paging must be specified as URL parameters.
When the selected Paging mechanism is Paging marker:
- In the Marker element field, type in the name of the response element, whose value will be used in the subsequent pagination requests to obtain the next set of items if the pagination results are truncated.
- In the Marker parameter field, type in the name of the parameter that will be used in the subsequent pagination requests, with the Marker element value, to obtain the next set of items.
When the selected Paging mechanism is Paging URL:
- In the Paging URL field, specify the JSON field in the response that contains the URL for the next page of data. The collector will continue querying the service until this field is empty.
When the selected Paging mechanism is URL parameters:
-
In the URL Parameters field, enter the parameters that must be appended to the query to get the next page of data.
noteYou can use variables from the response by placing the name of the field in curly brackets, for example,
startIndex={index}&count=100. -
Optionally, in the Total field, enter the JSON field in the response that indicates the total amount of records. If this field is not specified, the service will be called until an empty result set is returned.