Updating job sequences

Updates an existing job sequence, specified by the job sequence's Flow ID. A successful response returns the updated job sequence's details.

Notes:

Whenever you update a job sequence, make sure to publish your changes before starting the sequence.

Updating running job sequences

If you update or edit a job sequence while it is running, the system will stop the job sequence. If this occurs, you will have to publish your changes and then restart the job sequence from the beginning of the job sequence.

Example: A job sequence has Job 1, Job 2, and Job 3. Job 1 and Job 2 run in parallel and Job 3 depends on the completion of both Job 1 and Job 2. If you update or delete the job sequence and Job 1 completes ( Success, Failed, or Killed), Job 2 will be stopped by the system with the Killed job status. The job sequence will also be stopped by the system with the Killed job status. You will have to publish your changes and then restart the job sequence from the beginning of the job sequence.

Service URL

PUT /api/cx-unity-api/flows/{flowid}

Path parameters

flowId - The Flow ID of the job sequence to update.

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`

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 updated.
`jobId`	ID for the job updated.
`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

Update the job sequence with the flow ID = SampleSequence1.

PUT /api/cx-unity-api/flows/SampleSequence1

Request body:

{
  "flowName": "SampleSequence1",
  "flowId": "SampleSequence1",
  "description": "A sample job sequence",
  "active": true,
  "jobs": [
    {
      "id": "job2.1",
      "jobId": "CXU_JOB_1611731643985",
      "type": "INGEST",
      "description": "Ingest Customer",
      "depends": []
    },
    {
      "id": "job2.2",
      "jobId": "CXU_JOB_1611731863790",
      "type": "INGEST",
      "description": "Ingest Address",
      "depends": []
    },
    {
      "id": "job2.3",
      "jobId": "CXU_JOB_1611747658146",
      "type": "INGEST",
      "description": "Ingest Order",
      "depends": []
    },
    {
      "id": "job3",
      "jobId": "and_gate",
      "type": "GATE",
      "condition": "and",
      "depends": [
        "job2.1",
        "job2.2",
        "job2.3"
      ]
    },
    {
      "id": "job4",
      "jobId": "Dw",
      "type": "DW",
      "description": "Run DW",
      "depends": [
        "job3"
      ]
    },
    {
      "id": "job5",
      "jobId": "CXU_JOB_1611732176368",
      "type": "QUERYEXPORT",
      "description": "Export Customer",
      "depends": [
        "job4"
      ]
    }
  ],
  "schedule" : {
    "cronExpression" : "0 0 18 * * ?"
    },
  "notification": {
     "list": [
        "api.user@oracle.com",
        "api.second.user@oracle.com"
      ],
      "onlyFailure": false,
      "onlySummary": false,
   }
}

Response:

{
  "flowName": "SampleSequence1",
  "flowId": "SampleSequence1",
  "description": "A sample job sequence",
  "versionTS": 1612437111607,
  "active": true,
  "lastModifiedBy": "0d21396c936a4e41afda8d44523d6dc0",
  "createdTS": 1612437111607,
  "createdBy": "0d21396c936a4e41afda8d44523d6dc0",
  "jobs": [
    {
      "id": "job2.1",
      "jobId": "CXU_JOB_1611731643985",
      "type": "INGEST",
      "description": "Ingest Customer",
      "depends": []
    },
    {
      "id": "job2.2",
      "jobId": "CXU_JOB_1611731863790",
      "type": "INGEST",
      "description": "Ingest Address",
      "depends": []
    },
    {
      "id": "job2.3",
      "jobId": "CXU_JOB_1611747658146",
      "type": "INGEST",
      "description": "Ingest Order",
      "depends": []
    },
    {
      "id": "job3",
      "jobId": "and_gate",
      "type": "GATE",
      "condition": "and",
      "depends": [
        "job2.1",
        "job2.2",
        "job2.3"
      ]
    },
    {
      "id": "job4",
      "jobId": "Dw",
      "type": "DW",
      "description": "Run DW",
      "depends": [
        "job3"
      ]
    },
    {
      "id": "job5",
      "jobId": "CXU_JOB_1611732176368",
      "type": "QUERYEXPORT",
      "description": "Export Customer",
      "depends": [
        "job4"
      ]
    }
  ],
  "schedule" : {
    "cronExpression" : "0 0 18 * * ?"
    },
  "notification": {
    "left" : "HTTP",
    "right" : "ugey723t239uihjiwegyg2376u"
   }
}

Error responses

No job sequence found with flowId = Flow1: This message appears if the specified flowId does not exist. Ensure the flowId exists, and try again.

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

FlowId can't be null/blank: This message appears when updating a job sequence, and the flowId is not specified.

{
  "type": "",
  "title": "System Error",
  "detail": "FlowId can't be null/blank.",
  "o:errorCode": "InvalidFlowException",
  "o:errorDetails": []
}

FlowName can't be null/blank: This message appears when updating a job sequence, and the flowName is not specified.

{
  "type": "",
  "title": "System Error",
  "detail": "FlowName can't be null/blank.",
  "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": []
}

[Update job sequence, updating job sequences, update job sequencing, edit job sequence, editing job sequences, edit job flow]

Learn more

Job sequences

Managing job sequences

Viewing job sequence run details