Skip to content

API v1 - Shared jobs

The shared jobs endpoint allows users to explore what shared jobs, packages, and revisions are available on the Matillion ETL instance, as well as importing, exporting, and deleting shared jobs, packages, and revisions.

A "package" represents a folder that can house both other packages and shared jobs. A "package name" is the concatenated path of packages that leads to the shared job. The "package name" shouldn't be mistaken for the literal name of a single package. Nested packages are denoted by a period/full stop. For example, a package name could be packageA.packageB.packageC. If a single package's name includes a space, replace the space with %20 in your API request.

A "revision" is the revision number of the shared job. When first creating the shared job, the default revision is 1.

Read Shared job configuration for more information.

You can manage your shared jobs in your Matillion ETL instance by clicking the Project Menu, then Manage Shared Jobs.

Prerequisites

  • To use Matillion ETL API services, you must know how to make REST API calls, either by employing a REST API GUI client such as Postman, or employing a command line interface (CLI) like cURL.
  • If you are new to Matillion ETL's API, read our Matillion API introduction and explore the v1 API map.
  • Matillion ETL API endpoints require authorization to make any REST API call, so ensure a username and password for the Matillion ETL instance is configured before making any API call.

Using the API

Access shared jobs from a Matillion ETL instance by making GET, POST or DELETE calls with the form:

<instanceAddress>/rest/v1/sharedjob/<endpoint>

Where:

  • <instanceAddress> is the URI of your Matillion ETL instance in the form http://host:port.
  • <endpoint> is the name of the API endpoint that accomplishes the task you want to perform. These endpoints are documented in the following sections.

Note

There are often multiple ways of achieving the same task within the API as resources and methods branch out and overlap. For example, you can usually delete resources by using either POST or DELETE calls.

GET export

To export the shared jobs metadata from within your Matillion ETL instance, make the following GET call:

<instanceAddress>/rest/v1/sharedjob/export

A GET call to the endpoint will return the following response from the server, in JSON format:

{
    "objects": [
        {
            "metadata": {
                "identifier": {... }
                    ]
                },...
                "orchestrationJobs": [
                    "Shared Jobs - Unicode"
                ],...
                "transformationJobs": [],
                    },
                    "variables": {
                        "oauth": {....}
                    },  ....
    ],
    "version": "master",
    "environment": "redshift"
}

POST import

To import shared jobs metadata into a Matillion ETL instance, make the following POST call:

<instanceAddress>/rest/v1/sharedjob/import

The data to be imported should be put in the POST body, in JSON format. The format of this will be exactly the same as the server response from a GET export call.

A POST call to the endpoint will return the following response from the server, in JSON format:

{
  "name": "sharedjobs",
  "statusList": [
    {
      "success": true,
      "name": "matillion.regression.Unicode_1.1"
    },
     {
      "success": true,
      "name": "Matillion.Incremental.Gmail Incremental Load.1",
    }
  ],....
  "success": true
}

GET package

To get the shared jobs packages available within Matillion ETL, make the following GET call:

<instanceAddress>/rest/v1/sharedjob/package

A GET call to the endpoint will return the following response from the server, in JSON format:

[
    "TestPackage-1",
    "TestPackage-2",
    "TestPackage-3"
]

GET package export

To export a specific shared job package, make the following GET call:

<instanceAddress>/rest/v1/sharedjob/package/name/<packageName>/export

Where <packageName> is the name of the package you want to export. You can obtain package names by calling GET package.

A GET call to the endpoint will return the following response from the server, in JSON format:

{
    "objects": [
        {
            "metadata": {...},
            "orchestrationJobs": {...}
            "transformationJobs": {...},
        },
    ],
    "version": "master",
    "environment": "redshift"
}

GET package job

To get a list of shared jobs available within the package, make the following GET call:

<instanceAddress>/rest/v1/sharedjob/package/name/<packageName>/job

Where <packageName> is the name of the package you want to examine. You can obtain package names by calling GET package.

A GET call to the endpoint will return the following response from the server, in JSON format:

[
    "SharedJob"
]

POST package delete

To delete a package from the Matillion ETL instance, make the following POST call:

<instanceAddress>/rest/v1/sharedjob/package/name/<packageName>/delete

Where <packageName> is the name of the package you want to delete. You can obtain package names by calling GET package.

The POST call does not require a body to be specified.

A POST call to the endpoint will return the following response from the server, in JSON format:

{
  "success": true,
  "msg": "Successfully deleted [3] Shared Job(s).",
  "id": -1
}

Alternatively, use a DELETE API call, as described below.

DELETE package

To delete a package from the Matillion ETL instance, make the following DELETE call:

<instanceAddress>/rest/v1/sharedjob/package/name/<packageName>/delete

Where <packageName> is the name of the package you want to delete. You can obtain package names by calling GET package.

A DELETE call to the endpoint will return the following response from the server, in JSON format:

{
    "success": true,
    "msg": "Successfully deleted [4] Shared Job(s).",
    "id": -1
}

GET job export

To export the metadata for a specific shared job from within the shared job package, make the following GET call:

<instanceAddress>/rest/v1/sharedjob/package/name/<packageName>/job/name/<jobName>/export

Where:

  • <packageName> is the name of the package containg the shared job. You can obtain package names by calling GET package.
  • <jobName> is the name of the shared job you want to export. You can obtain shared job names by calling [GET package job]](#get-package-job).

A GET call to the endpoint will return the following response from the server, in JSON format:

{
    "objects": [
        {
            "metadata": {...},
            "orchestrationJobs": {...},
            "transformationJobs": {...},
        },
    ],
    "version": "master",
    "environment": "redshift"
}

GET job revision

To get the revision id associated with a specific shared job, make the following GET call:

<instanceAddress>/rest/v1/sharedjob/package/name/<packageName>/job/name/<jobName>/revision

Where:

  • <packageName> is the name of the package containg the shared job. You can obtain package names by calling GET package.
  • <jobName> is the name of the shared job you want to export. You can obtain shared job names by calling GET package job.

A GET call to the endpoint will return the following response from the server, in JSON format:

[
    1
]

POST job delete

To delete a shared job from the Matillion ETL instance, make the following POST call:

<instanceAddress>/rest/v1/sharedjob/package/name/<packageName>/job/name/<jobName>/delete

Where:

  • <packageName> is the name of the package containg the shared job. You can obtain package names by calling GET package.
  • <jobName> is the name of the shared job you want to export. You can obtain shared job names by calling GET package job.

The POST call does not require a body to be specified.

A POST call to the endpoint will return the following response from the server, in JSON format:

{
    "success": true,
    "msg": "Successfully deleted [1] Shared Job(s).",
    "id": -1
}

DELETE job

To delete a shared job from the Matillion ETL instance, make the following DELETE call:

<instanceAddress>/rest/v1/sharedjob/package/name/<packageName>/job/name/<jobName>/delete

Where:

  • <packageName> is the name of the package containg the shared job. You can obtain package names by calling GET package.
  • <jobName> is the name of the shared job you want to export. You can obtain shared job names by calling GET package job.
{
    "success": true,
    "msg": "Successfully deleted [1] Shared Job(s).",
    "id": -1
}

GET revision export

To export the metadata for a specific shared job revision, make the following GET call:

<instanceAddress>/rest/v1/sharedjob/package/name/<packageName>/job/name/<jobName>/revision/id/<revisionId>/export

Where:

  • <packageName> is the name of the package containg the shared job. You can obtain package names by calling GET package.
  • <jobName> is the name of the shared job you want to export. You can obtain shared job names by calling GET package job.
  • <revisionId> is the id of a specific shared job revision. You can obtain a revision id by calling GET job revision.

A GET call to the endpoint will return the following response from the server, in JSON format:

{
    "endpoints": [
        {...}
    ],
    "dataTypes": [...]
}

POST revision delete

To delete a specific shared job revision, make the following POST call:

<instanceAddress>/rest/v1/sharedjob/package/name/<packageName>/job/name/<jobName>/revision/id/<revisionId>/delete

Where:

  • <packageName> is the name of the package containg the shared job. You can obtain package names by calling GET package.
  • <jobName> is the name of the shared job you want to export. You can obtain shared job names by calling GET package job.
  • <revisionId> is the id of a specific shared job revision. You can obtain a revision id by calling GET job revision.

The POST call does not require a body to be specified.

A POST call to the endpoint will return the following response from the server, in JSON format:

{
    "success": true,
    "msg": "Successfully deleted [1] Shared Job(s).",
    "id": -1
}

DELETE revision

To delete a specific shared job revision from the Matillion ETL instance, make the following DELETE call:

<instanceAddress>/rest/v1/sharedjob/package/name/<packageName>/job/name/<jobName>/revision/id/<revisionId>

Where:

  • <packageName> is the name of the package containg the shared job. You can obtain package names by calling GET package.
  • <jobName> is the name of the shared job you want to export. You can obtain shared job names by calling GET package job.
  • <revisionId> is the id of a specific shared job revision. You can obtain a revision id by calling GET job revision.

A DELETE call to the endpoint will return the following response from the server, in JSON format:

{
    "success": true,
    "msg": "Successfully deleted [1] Shared Job(s).",
    "id": -1
}
© Copyright 2024 Matillion Ltd | Legal | Privacy Policy | Disclaimer | Modern Slavery Statement