Use the job instance APIs to manage ingress, egress, and match and merge jobs. You can create and run job instances, search for job instances, and retrieve a short summary or the complete details of a job instance. The APIs use the jobInstance resource.
Create Ingress Job Instance
Use the Create Ingress Job Instance API to create and run an ingress job instance that imports data from an external source system to Business 360 data store.
Before using this API, you must first define an ingress job in Business 360 Console. For more information about defining an ingress job, see Ingress data.
The API supports the POST method.
POST request
To create and run an ingress job instance, submit a POST request with the following URI:
POST <baseApiURL>/job/public/api/v1/jobInstance/Ingress
You can use the following parameters in the request body:
Parameter
Type
Description
jobDefinitionId
String
The internal ID of a job.
You can view the internal ID of a job when you open the job definition in Business 360 Console.
POST response
The response is in the JSON format. The response shows the HTTP 200 OK response code and returns the ID of job instance.
POST example
You might use the following sample request to create and run an ingress job instance:
POST <baseApiUrl>/job/public/api/v1/jobInstance/Ingress Content-Type: application/json IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
{
"jobDefinitionId": "ingress_org"
}
The following sample response contains the HTTP 200 OK response code and the job instance ID:
HTTP/1.1 200 OK Content-Type: application/json
{ "id": "714189942313869312" }
Note: Use the value of id to retrieve a summary or the complete details of a job instance. For more information about retrieving a summary of a job instance, see Read Job Instance Summary. For more information about retrieving the complete details of a job instance, see Read Job Instance Details.
Create Egress Job Instance
Use the Create Egress Job Instance API to create and run an egress job instance that exports data from Business 360 data store to an external data source.
Before using this API, you must first define an egress job in Business 360 Console. For more information about defining an egress job, see Egress data.
The API supports the POST method.
POST request
To create and run an egress job, submit a POST request with the following URI:
POST <baseApiURL>/job/public/api/v1/jobInstance/Egress
You can use the following parameters in the request body:
Parameter
Type
Description
jobDefinitionId
String
The internal ID of a job.
You can view the internal ID of a job when you open the job definition in Business 360 Console.
POST response
The response is in the JSON format. The response shows the HTTP 200 OK response code and returns the ID of job instance.
POST example
You might use the following sample request to create and run an egress job instance:
POST <baseApiUrl>/job/public/api/v1/jobInstance/Egress Content-Type: application/json IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
{
"jobDefinitionId": "egress_org"
}
The following sample response contains the HTTP 200 OK response code and the job instance ID:
HTTP/1.1 200 OK Content-Type: application/json
{ "id": "714195872447352832" }
Note: Use the value of id to retrieve a summary or the complete details of a job instance. For more information about retrieving a summary of a job instance, see Read Job Instance Summary. For more information about retrieving the complete details of a job instance, see Read Job Instance Details.
Create Match and Merge Job Instance
Use the Create Match and Merge Job Instance API to create and run a match and merge job that matches records, merges the matched records, performs both matching and merging, or resets matched records.
Before using this API, you must first define a match and merge job in Business 360 Console. For more information about defining a match and merge job, see Define and run a match and merge job.
When you run the Create Match and Merge Job Instance API, you can specify the following types of match and merge processes:
•Match Only
•Merge Only
•Match and Merge
•Reset Matched Records
The API supports the POST method.
POST request
To create and run a match and merge job, submit a POST request with the following URI:
POST <baseApiURL>/job/public/api/v1/jobInstance/MatchMerge
You can use the following parameters in the request body:
Parameter
Type
Description
jobDefinitionId
String
The internal ID of a job.
You can view the internal ID of a job when you open the job definition in Business 360 Console.
matchModelId
String
The ID of the match model. You can view the ID of match model when you open it in Business 360 Console.
matchModelVersion
String
The version of the match model.
parameters
Array
List of parameters that specify the details of a match and merge job definition.
parameters > name
String
Name of a parameter for which you want to specify a value. The supported value is processType.
parameters > value
String
Type of match and merge process that the job is configured to perform.
You can use one of the following values:
- Match Only. Identifies matching records.
- Merge Only. Merges matching records that are identified by the match process based on the merge strategy.
- Match and Merge. Identifies matching records and merges them based on the merge strategy.
- Reset Matched Records. Resets the matched records that aren't yet merged and makes the records available for matching again.
Note: The matchModelId and matchModelVersion parameters aren't required for the Reset Matched Records process type.
Note: The API retrieves the business entity details directly from the job definition, eliminating the need for the businessEntity parameter in the request body. If you include the parameter in the request body, the API ignores the parameter and processes the request.
POST response
The response is in the JSON format. The response shows the HTTP 200 OK response code and returns the ID of job instance.
POST example
You might use the following sample request to create and run a match and merge job that identifies matching records:
POST <baseApiUrl>/job/public/api/v1/jobInstance/MatchMerge Content-Type: application/json IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
The following sample response contains the HTTP 200 OK response code and the job instance ID:
HTTP/1.1 200 OK Content-Type: application/json
{ "id": "714542403541159936" }
Note: Use the value of id to retrieve a summary or the complete details of a job instance. For more information about retrieving a summary of a job instance, see Read Job Instance Summary. For more information about retrieving the complete details of a job instance, see Read Job Instance Details.
Search Job Instances
Use the Search Job Instances API to search for matching job instances based on the job name, the job type, the status of job instances, or the user who started the job instance.
The API supports the POST method.
POST request
To search for ingress, egress, and match and merge jobs, submit a POST request with the following URI:
POST <baseApiURL>/job/public/api/v1/search
You can use the following parameters in the request body:
Parameter
Type
Description
search
String
Search string to search for matching job name, job type, status of job instances, or user who started the job instance.
pageSize
Number
Number of search results to display on each page. Minimum value is 1.
pageOffset
Number
Optional. Number of pages to skip. For example, pageOffset=2 means that the search must skip the first two pages of the search results. Minimum value is 0.
filter
Array
Specifies a list of fields that you want to use to filter the search results.
filters > operator
String
The boolean operator that joins multiple filters. Use AND or OR as the boolean operator.
Use AND if fieldName has different values. Use OR if fieldName has the same values but fieldValue has different values.
fieldName
String
Type of value based on which you want to filter job instances.
Use one of the following value types:
- name. Filters job instances based on the specified job name.
- status. Filters job instances based on the specified job status.
- jobType. Filters job instances based on the specified job type.
fieldValue
String
Value based on which you want to filter the job instances.
POST response
The response is in the JSON format. The response returns the matching job instances.
The response includes the following parameters:
Parameter
Type
Description
totalRecords
Number
The number of job instances returned in the search.
totalPages
Number
The number of pages returned in the search.
currentPage
Number
The page number from which you view the search results.
jobInstances
Array
The list of job instances returned in the search.
metadataEntities
String
The metadata details of the job instance.
runTimeParameters
String
The runtime parameters that were used to run the job instance.
jobLevelMetrics
String
The key metrics of the job instance.
completedAt
String
Date when the job instance was completed.
state
String
Status of job instances.
createdAt
String
Date when the job was created.
createdBy
String
Name of the user who created the job.
updatedAt
String
Date when the job was updated.
updatedBy
String
Name of the user who last updated the job.
startedAt
String
Date when the job instance was started.
startedBy
String
Name of the user who started the job instance.
isCompleted
Boolean
Indicates whether the job instance was completed.
POST example
You might use the following request to search for a job:
POST <baseApiUrl>/job/public/api/v1/search Content-Type: application/json IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
Use the Read Job Instance Summary API to retrieve a brief summary about the job instance. The summary contains the details of runtime parameters and metrics of a job instance.
The API supports the GET method.
GET request
To retrieve the summary of a job instance, submit a GET request with the following URI:
GET <baseApiURL>/job/public/api/v1/jobInstance/<jobInstanceId>
The GET request contains the following path parameters:
Parameter
Type
Description
jobInstanceId
String
The ID of the job instance.
GET response
The response is in the JSON format. The response body contains the summary of a job instance.
The GET response includes the following parameters:
Parameter
Type
Description
metadataEntities
String
The metadata details of the job instance.
runTimeParameters
String
The runtime parameters that were used to run the underlying taskflow related to the job.
jobLevelMetrics
String
The key metrics of the job instance.
completedAt
String
Date when the job was completed.
state
String
Indicates the status of the job. The job instance can have one of the following statuses:
- RUNNING. Indicates that the job is being processed.
- SUCCESS. Indicates that the job was successful.
- FAILED. Indicates that the job failed.
- STOPPED. Indicates that the job was stopped.
- WARNING. Indicates that the job completed with warnings.
- SKIPPED. Indicates that the job was skipped and not processed by MDM SaaS.
- QUEUED. Indicates that the job was queued.
createdAt
String
Date when the job was created.
createdBy
String
Name of the user who created the job.
updatedAt
String
Date when the job was updated.
updatedBy
String
Name of the user who last updated the job.
startedAt
String
Date when the job was started.
startedBy
String
Name of the user who started the job.
isCompleted
Boolean
Indicates whether the job was completed.
Note: All dates are in the Unix epoch time format.
GET example
You might use the following request to retrieve the summary of a job instance based on the job instance ID 93d25c14-c874-438b-8ed0-442944a37a54:
GET <baseApiURL>/job/public/api/v1/jobInstance/93d25c14-c874-438b-8ed0-442944a37a54 Content-Type: application/json IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
The sample response shows the HTTP 200 OK response code and retrieves the summary of a job instance.
Use the Read Job Instance Details API to retrieve the complete details of a job instance. The details include a brief summary of the job instance and the information about steps related to the job instance.
The API supports the GET method.
GET request
To retrieve the details of a job instance, submit a GET request with the following URI:
GET <baseApiURL>/job/public/api/v1/jobInstance/<jobInstanceId>?details=true
The GET request contains the following path parameters:
Parameter
Type
Description
jobInstanceId
String
The ID of the job instance.
GET response
The response is in the JSON format. The response body contains the complete details of a job instance.
The GET response includes the following parameters:
Parameter
Type
Description
metadataEntities
String
The metadata details of the job instance.
runTimeParameters
String
The runtime parameters that were used to run the underlying taskflow related to the job.
jobLevelMetrics
String
The key metrics of the job instance.
steps
String
Lists the steps and their details.
completedAt
String
Date when the job was completed.
state
String
Indicates whether the job was successful.
createdAt
String
Date when the job was created.
createdBy
String
Name of the user who created the job.
updatedAt
String
Date when the job was updated.
updatedBy
String
Name of the user who last updated the job.
startedAt
String
Date when the job was started.
startedBy
String
Name of the user who started the job.
isCompleted
Boolean
Indicates whether the job was completed.
Note: All dates are in the Unix epoch time format.
GET example
You might use the following request to retrieve the details of a job instance based on the job instance ID 93d25c14-c874-438b-8ed0-442944a37a54:
GET <baseApiURL>/job/public/api/v1/jobInstance/93d25c14-c874-438b-8ed0-442944a37a54?details=true Content-Type: application/json IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
The following sample response shows the HTTP 200 OK response code and retrieves the details of a job instance: