Creating job sequences

This endpoint enables you to create a job sequence. Consider the following example of creating a new job sequence:

You want to start the job sequence by running an ingest job to import the most up-to-date data into the Oracle Unity data model.
Once the ingest job has completed and imported data, the data warehouse job will process and validate the imported data.
When the data warehouse job has completed and processed the data, the identity resolution pipeline job will match up and unify customer records.
When the identity resolution pipeline job has completed and processed the unified data, a campaign will export a segment using the imported, processed and unified data.

The image below illustrates the workflow of this job sequence. Refer to the example tab for the request and response details for this job sequence.

After you've learned how to create a basic job sequence, see more advanced topics such as:

Note: After you create a job sequence, remember to publish your changes so any new job sequences are ready to run.

Service URL

POST {host}/api/cx-unity-api/flows

Request parameters

Name	Type	Required?	Description	Possible values
`flowName`	string	yes	Name of the job sequence to create. 255 characters.
`flowId`	string	yes	A unique identifier for the job sequence to create. Must be unique. 255 characters.
`description`	string	no	A description of the job sequence to create. 250 characters.
`active`	boolean	yes	Whether the job sequence will be active. A job sequence must be active before it can be started.	`true` `false`
`jobs`	array	yes	Array of jobs within the job sequence. See below for details.

Nested schema: jobs

Name	Type	Required?	Description	Possible values	Example
`id`	string	yes	Specify a unique ID for the job. This `id` must be unique within this job sequence. If you want to include one job in a job sequence multiple times, each `id` must be unique. Must not contain spaces and special characters.		job1 job1.1
`jobId`	string	yes	The unique ID for the job. You can obtain a job's `jobId` using the following endpoints: GET /metadata/jobs GET /metadata/jobs/{jobType}
`type`	string	yes	The job type to run. See the Unity Help Center for more information about the different jobs types.	`EXPORT` (Data object export job) `QUERYEXPORT` (Segment export job) `CAMPAIGN` (Campaign job) `INGEST` (Ingest job) `PUBLISH` (Publish job) `DW` (Data warehouse job) `ANALYTICS` (Identity resolution pipeline job) `IDGRAPH` (Customer 360 job) `GATE` (used to create job sequence conditions)
`condition`	string	yes (if gate)	If `GATE` is specified for the job type, condition must be `and` or `or`. See Creating job sequence conditions for more information and examples.	`and` `or`
`description`	string	no	A description of the job.
`depends`	array	no	Specify a job dependency before this job runs by specifying the job's `jobId`. If specified, the specified `jobId` needs to be complete before the next job in the sequence runs. The first job in the job sequence with an empty `depends` array will be the starting job in the sequence. To specify more than one job in a `depends` array, use a `GATE` job type.		This is the starting job in the job sequence. "depends": [ ] This job will start after "job1" is complete. "depends": [ "job1" ]

Nested schema: schedule

Scheduling job sequences is optional. See Scheduling job sequences for more information.

Name	Type	Required?	Description	Example
`cronExpression`	string	no, only required if `schedule` is specified	Date and time for the job sequence to run, expressed as a Cron Expression. You can build your Cron Expression using tools such as CronMaker and FreeFormatter. See Scheduling job sequences for more details and examples.	Run the job sequence every 12 hours: "schedule": { "cronExpression": "0 0 0/12 1/1 * ? " } Run the job sequence daily at 9AM: "schedule": { "cronExpression": "0 0 9 1/1 ? *" }

Name

Type

Required?

Description

Example

cronExpression

string

no, only required if schedule is specified

Date and time for the job sequence to run, expressed as a Cron Expression. You can build your Cron Expression using tools such as CronMaker and FreeFormatter.

See Scheduling job sequences for more details and examples.

Run the job sequence every 12 hours:

"schedule": {
  "cronExpression": "0 0 0/12 1/1 * ? *"
}

Run the job sequence daily at 9AM:

"schedule": {
  "cronExpression": "0 0 9 1/1 * ? *"
}

Nested schema: notification

Email notifications are optional. See Configuring job sequence notifications for more information.

Name	Type	Required?	Description	Possible values
`list`	array	no, only required if `notification` is specified	Array of email addresses. The email addresses specified here will receive email notifications when individual jobs succeed and fail, and also when the entire job sequence succeeds and fails.
`onlyFailure`	boolean	no	Flag to enable sending email notifications for failure notifications only. If set to `true`, the email addresses specified will be notified when individual jobs in the sequence fail, and when the entire sequence fails. The default is `false`.	`true` `false`
`onlySummary`	boolean	no	Flag to enable sending email notifications for job sequence summary notifications only. If set to `true`, the email addresses specified will be notified when the entire job sequence succeeds and fails. The default is `false`.	`true` `false`

Request notes:

The first job in the sequence with an empty depends array, will be the starting job in the sequence.
To create a job with more than one dependent job, use a gate. See Creating job sequence conditions for more information and examples.

Response parameters

Name	Description
`flowName`	Name of the job sequence.
`flowId`	The job sequence ID.
`description`	The description of the job sequence .
`versionTS`	Timestamp when the job sequence was created.
`active`	Whether the job sequence is active. Job sequences must be active before they can be started.
`lastModifiedBy`	Timestamp when the job sequence was last updated.
`createdTS`	Timestamp when the job sequence was created.
`createdBy`	ID of the user who created the job sequence.

Nested schema: jobs

Name	Description
`id`	Name of the job created.
`jobId`	ID for the job created.
`type`	Job type.
`description`	Description of the job.
`depends`	Array that lists job dependencies.

Nested schema: schedule

Name	Description
`cronExpression`	The date and time the job sequence is scheduled to run, represented as a Cron Expression.

Nested schema: notification

Name	Type	Description	Possible values
`list`	array	Array of email addresses. The email addresses specified here will receive email notifications when individual jobs succeed and fail, and also when the entire job sequence succeeds and fails.
`onlyFailure`	boolean	Flag to enable sending email notifications for failure notifications only. If set to `true`, the email addresses specified will be notified when individual jobs in the sequence fail, and when the entire sequence fails. The default is `false`.	`true` `false`
`onlySummary`	boolean	Flag to enable sending email notifications for job sequence summary notifications only. If set to `true`, the email addresses specified will be notified when the entire job sequence succeeds and fails. The default is `false`.	`true` `false`
`left`	string	The system returns this value to indicate the recipient of the email notification. This is a read-only property.
`right`	string	The system returns this value to indicate the recipient of the email notification. This is a read-only property.

Example

Create a standard job sequence for the following scenario:

You want to start the job sequence by running an ingest job to import the most up-to-date data into the Oracle Unity data model.
Once the ingest job has completed and imported data, the data warehouse job will process and validate the imported data.
When the data warehouse job has completed and processed the data, the identity resolution pipeline job will match up and unify customer records.
When the identity resolution pipeline job has completed and processed the unified data, a campaign will export a segment using the imported, processed and unified data.

Here's an illustration of this job sequence:

Create the job sequence illustrated above:

POST /api/cx-unity-api/flows

Request body:

{
  "flowName": "Job_Sequence_Example1",
  "flowId": "Job_Sequence_Example1",
  "description": "This is my first job sequence. Ingest job, then data warehouse job, followed by ID resolution job, to campaign job.",
  "active": true,
  "jobs": [
    {
      "id": "job1",
      "jobId": "CXU_JOB_1604904383636",
      "type": "INGEST",
      "description": "Ingest Job",
      "depends": [
        
      ]
    },
    {
      "id": "job2",
      "jobId": "Dw",
      "type": "DW",
      "description": "Data warehouse job",
      "depends": [
        "job1"
      ]
    },
    {
      "id": "job3",
      "jobId": "Analytics",
      "type": "ANALYTICS",
      "description": "Identity resolution pipeline job",
      "depends": [
        "job2"
      ]
    },
    {
      "id": "job4",
      "jobId": "CXU_JOB_1689345602395",
      "type": "CAMPAIGN",
      "description": "Campaign job",
      "depends": [
        "job3"
      ]
    }
  ]
}

Response:

{
  "flowName": "Job_Sequence_Example1",
  "flowId": "Job_Sequence_Example1",
  "description": "This is my first job sequence. Ingest job, then data warehouse job, followed by ID resolution job, to campaign job.",
  "versionTS": 1612437111607,
  "active": true,
  "lastModifiedBy": "0d21396c936a4e41afda8d44523d6dc0",
  "createdTS": 1612437111607,
  "createdBy": "0d21396c936a4e41afda8d44523d6dc0",
  "jobs": [
    {
      "id": "job1",
      "jobId": "CXU_JOB_1604904383636",
      "type": "INGEST",
      "description": "Ingest Job",
      "depends": [
        
      ]
    },
    {
      "id": "job2",
      "jobId": "Dw",
      "type": "DW",
      "description": "Data warehouse job",
      "depends": [
        "job1"
      ]
    },
    {
      "id": "job3",
      "jobId": "Analytics",
      "description": "Identity resolution pipeline job",
      "type": "ANALYTICS",
      "depends": [
        "job2"
      ]
    },
    {
      "id": "job4",
      "jobId": "CXU_JOB_1689345602395",
      "type": "CAMPAIGN",
      "description": "Campaign job",
      "depends": [
        "job3"
      ]
    }
  ]
}

Error responses

A job sequence with flowId = Flow1 already exists: This message appears if the specified flowId already exists. Ensure the flowId for the job sequence is unique, and then try again.

{
  "type": "",
  "title": "System Error",
  "detail": "A job sequence with flowId = Flow1 already exists.",
  "o:errorCode": "InvalidFlowException",
  "o:errorDetails":[]
}

Value for Job id is missing: This message appears when updating a job sequence, but the jobId is not specified.

{
  "type": "",
  "title": "System Error",
  "detail": "Value for Job id is missing.",
  "o:errorCode": "InvalidFlowException",
  "o:errorDetails": []
}

Value for Job id is not unique: This message appears when updating a job sequence, but the jobId specified is not unique within the job sequence.

{
  "type": "",
  "title": "System Error",
  "detail": "Value for Job id is not unique.",
  "o:errorCode": "InvalidFlowException",
  "o:errorDetails": []
}

The job sequence requires more than one job in its configuration: This message appears when saving or updating a job sequence, and the sequence does not contain more than 1 job. A job sequence must contain at least 2 jobs.

{
  "type": "",
  "title": "System Error",
  "detail": "The job sequence requires more than one job in its configuration.",
  "o:errorCode": "InvalidFlowException",
  "o:errorDetails": []
}

Individual jobs can't have more than one dependent job. Configure multiple dependent jobs using the \"GATE\" type: This message appears when a job has more than 1 dependent job. To configure a job with more than 1 dependent job, you must configure the job as a gate.

{
  "type": "",
  "title": "System Error",
  "detail": "Individual jobs can't have more than one dependent job. Configure multiple dependent jobs using the \"GATE\" type.",
  "o:errorCode": "InvalidFlowException",
  "o:errorDetails": []
}

The \"GATE\" job type requires more than one job in the \"depends\" parameter: This message appears when a gate job type does not have more than 1 job. Gate job types must have more than 1 job configured.

{
  "type": "",
  "title": "System Error",
  "detail": "The \"GATE\" job type requires more than one job in the \"depends\" parameter.",
  "o:errorCode": "InvalidFlowException",
  "o:errorDetails": []
}

The cronExpression value for scheduling the job sequence is invalid: This message appears when an invalid cronExpression is specified. See Scheduling job sequences for more information.

{
  "type": "",
  "title": "System Error",
  "detail": "The cronExpression value for scheduling the job sequence is invalid.",
  "o:errorCode": "InvalidFlowException",
  "o:errorDetails": []
}

A loop is detected in this job sequence, so it can't be created/edited: This message appears when saving or updating a job sequence that contains a loop. Verify your job sequence's gate dependencies do not contain a loop.

{
  "type": "",
  "title": "System Error",
  "detail": "A loop is detected in this job sequence, so it can't be created/edited. Make sure that job dependencies
in the job sequence don't cause looping and re-submit your request.",
  "o:errorCode": "InvalidFlowException",
  "o:errorDetails": []
}

[create job sequences, job sequences create, create job sequence]

Next steps

Scheduling job sequences

Creating job sequence conditions

Configuring job sequence notifications

Learn more

Job sequences

Managing job sequences

Viewing job sequence run details