REST API Reference > Platform REST API version 3 resources > Object state synchronization
  

Object state synchronization

If you migrate an object from one organization to another, you can use the fetchState and loadState resources to synchronize the object states and run time attributes between the organizations.
For example, in Organization A, a mapping task with a Sequence Generator transformation has a NEXTVAL value of 3270. The same task was migrated to Organization B, however the NEXTVAL value in Organization B is 0. You want to synchronize the task's state between Organization A and Organization B so that the NEXTVAL value in both organizations has a value of 3270. You use the fetchState and loadState resources to synchronize the NEXTVAL value so that you can run the task in Organization B while preserving the sequence of numbers.
You can make up to 100 fetchState and 100 loadState calls each day.
To use the fetchState and loadState resources, the organizations must have the appropriate license.
The process of synchronizing object states is similar to the process of migrating objects. To synchronize object states, you fetch the states in the primary organization using the fetchState resource, and you load them into the target organization using the loadState resource.

fetchState

Use this resource with the loadState resource to synchronize object states across organizations.
Use the fetchState resource to create an object states package that you upload into other organizations using the loadState resource.
Creating the object states package includes a series of requests and responses, similar to the process of exporting assets. The end result is a ZIP file that contains the object states that you want to load to other organizations. To create the object states package, you perform the following tasks:
  1. 1Send a lookup GET request to receive the object IDs for the object states you want to synchronize.
    2. Informatica Intelligent Cloud Services returns the object IDs.
    See Lookup.
  2. 2Send a fetchState POST request to start the job, using the object IDs returned in the lookup response.
    3. Informatica Intelligent Cloud Services returns the job ID for the fetchState job.
    See Starting a fetchState job.
  3. 3Send a fetchState GET request to get the status of the job, using the fetchState job ID for the object state package.
    4. Informatica Intelligent Cloud Services returns the job ID and status. The response can also include a list of the object IDs and associated object states that are in the package.
    See Getting the fetchState job status.
  4. 4Send a fetchState GET request to download the package.
    5. Informatica Intelligent Cloud Services returns the package in a ZIP file.
    See Downloading an object states package.
The object states package contains state information in a JSON file for each object. Each file name uses the following format:
<task name>.<task type>.runtime.json
For example, a file with the name of mt_MappingTask106.MTT.runtime.json might contain the following data:
{
"taskRun" : {
"lastRuntime" : "2018-12-13T09:05:17.000Z"
},
"taskStateVariables" : [ {
"category" : "TX_VARIABLE",
"name" : "Sequence",
"value" : "26908"
} ]
}
You can change the following attributes in an object state file if required:
Other changes to the files in the package can cause unexpected behavior or errors.

Starting a fetchState job

Use a POST request to start a fetchState job.

POST request

To start the job, use the following URI:
/public/core/v3/fetchState
Include the following fields in the request:
Field
Type
Required
Description
name
String
Name of the fetchState job. If blank, default is job-<currentTimeInMilliseconds>
objects
Collection <complex type>
Yes
Object IDs for the states to include in the object state package.
Note: Informatica recommends that you include no more than 1000 objects in a package.
id
String
Yes
Included in the objects object.
Global unique identifier for the object for which the state is requested. This can be a project, folder, or asset ID.
includeDependencies
Boolean
Included in the objects object.
Determines whether to include the dependent objects' states.
Default is True.

POST request example

You might use a request similar to the following example:
POST <baseApiUrl>/public/core/v3/fetchstate
Content-Type: application/json
Accept: application/json
INFA-SESSION-ID: <sessionId>

{
"name" : "fetchStateJob1",
"objects" : [
{
"id": "l7bgB85m5oGiXObDxwnvK9",
"includeDependencies" : true
},
{
"id": "1MW0GDAE1sFgnvWkvom7mK",
"includeDependencies" : false
},
{
"id": "iIVBNZSpUKFg4N6g2PKUox"
}
]
}

POST response

If successful, returns the following information for the fetchState job:
Field
Type
Description
id
String
ID of the fetchState job.
createTime
String
Time object state package was created.
updateTime
String
Time object state package was last updated.
name
String
Name of the fetchState job.
startTime
String
Time the fetchState job was started.
endTime
String
Time the fetchState job ended.
status
Complex type
Status of the job.
state
String
Returned in the status object.
Status of the fetchState job, such as In Progress, Success, or Failed.
message
String
Returned in the status object.
Job status message.
objects
Collection
Collection of objects and object level status. Returns null if blank.

POST response examples

If successful, you might receive a response similar to the following example:
{
"id": "7evG9CokA1whk8ehF3opKM",
"createTime": "2018-10-26T08:15:48.502Z",
"updateTime": "2018-10-26T08:15:48.502Z",
"name": "fetchStateJob1",
"startTime": "2018-10-26T08:15:48.501Z",
"endTime": null,
"status": {
"state": "IN_PROGRESS",
"message": "In Progress"
},
"objects": null
}
If you receive an error, you might see a response similar to the following example:
{
"error": {
"code": "MigrationSvc_034",
"message": "User does not have required permissions.",
"requestId": "2ataXVlgw3ydI1Yb2MA4sq"
}
}

Getting the fetchState job status

Use a GET request to get the status of a fetchState job.

GET request

To get status of the fetchState job, use one of the following URIs:
Continue polling the request until the state is SUCCESSFUL.

GET response

A request for status returns the following status information:
Field
Type
Description
id
String
ID of the fetchState job.
createTime
String
Time the fetchState job was created.
updateTime
String
Last time the fetchState job was updated.
name
String
Name of the fetchState job.
startTime
String
Start time of the fetchState job.
endTime
String
End time of the fetchState job.
status
Complex type
Status of the fetchState job.
state
String
Returned in the status object.
State of the fetchState job, such as In Progress, Success, or Failed.
message
String
Returned in the status object.
Job status message.
objects
Collection
Objects in the fetchState job. Returned when the URI includes ?expand=objects
id
String
Returned in the objects object.
Global unique identifier for the object requested.
name
String
Returned in the objects object.
Name of the object..
path
String
Returned in the objects object.
Complete path of the object.
description
String
Returned in the objects object.
Description of the object.
status
Complex type
Returned in the objects object.
Status of the object.
state
String
Returned in the objects.status object.
Status of the object, such as IN PROGRESS, SUCCESS, FAILED, or SKIPPED.
message
String
Returned in the objects.status object.
Status message for the object.

GET response example

If your request for a fetchState job's status is successful, you might receive a response similar to the following example:
{
"id": "7evG9CokA1whk8ehF3opKM",
"createTime": "2018-10-26T08:15:48.502Z",
"updateTime": "2018-10-26T08:15:48.502Z",
"name": "fetchStateJob1",
"startTime": "2018-10-26T08:15:48.501Z",
"endTime": "2018-10-26T08:15:49.501Z",
"status": {
"state": "SUCCESSFUL",
"message": "Export completed successfully."
},
"objects": null
}
If your request included status for individual objects, a successful response might be similar to the following example:
{
"id": "7evG9CokA1whk8ehF3opKM",
"createTime": "2017-10-26T08:15:49.000Z",
"updateTime": "2017-10-26T08:15:50.000Z",
"name": "fetchStateJob1",
"startTime": "2018-10-26T08:15:49.000Z",
"endTime": "2018-10-26T08:15:50.000Z",
"status": {
"state": "SUCCESSFUL",
"message": "Export completed successfully."
},
"objects": [
{
"id": "1YmwRT083ZtfO04mUABaGF",
"name": "Mapping1",
"path": "/Mappings",
"type": "DTEMPLATE",
"description": "",
"status": {
"state": "SKIPPED",
"message": null
}
},
{
"id": "46MhQv9oxrgbOD6qtosF8t",
"name": "MappingTask1",
"path": "/Tasks",
"type": "MTT",
"description": "",
"status": {
"state": "SUCCESSFUL",
"message": null
}
},
{
"id": "7rM2ll1YjWYgHz4xiqRQO3",
"name": "Default",
"path": "/",
"type": "Project",
"description": "Auto-generated Default Project",
"status": {
"state": "SKIPPED",
"message": null
}
},
{
"id": "8suj2pxCujqh5Vtmv0DsyP",
"name": "Destination",
"path": "null",
"type": "Connection",
"description": "Dst Connection",
"status": {
"state": "SKIPPED",
"message": null
}
},
{
"id": "cpnxnIQMIYvkDOemLhFJ2q",
"name": "03",
"path": null,
"type": "AgentGroup",
"description": null,
"status": {
"state": "SKIPPED",
"message": null
}
},
{
"id": "gJvuKZZuBifk9MfZFxtPAb",
"name": "Source",
"path": null,
"type": "Connection",
"description": "Src Connection",
"status": {
"state": "SKIPPED",
"message": null
}
}
]
}

Downloading an object states package

Use a GET request to download an object states package.

GET request

To download the object states package, use the following URI:
/public/core/v3/fetchState/<id>/package
The <id> is the fetchState job ID.

GET response

If successful, you receive the ZIP stream in the response body and the response type is application/zip.
If unsuccessful, you might receive a response similar to the following example:
{
"error": {
"code": "MigrationSvc_017",
"message": "Export request with identifier [6GnKs0tkLHdE6Hpd5nsWD] doesnt exist.",
"debugMessage": "Export request with identifier [6GnKs0tkLHdE6Hpd5nsWD] doesnt exist.",
"requestId": "0FrZZzXiEoafqCZUPqJsYd"
}
}

loadState

Use this resource with the fetchState resource to synchronize object states across multiple organizations.
Loading object states includes a series of requests and responses. To load states into an organization, you perform the following tasks:
  1. 1Send a loadState POST request to upload the ZIP file.
    2. Informatica Intelligent Cloud Services returns the job ID for the loadState job.
    See Uploading an object states package.
  2. 2Send a loadState POST request to load the object states. The request includes the loadState job ID and a list of object IDs associated with the states you want to load.
    3. Informatica Intelligent Cloud Services returns the status of the job such as IN PROGRESS or SUCCESS, or returns an error message. The response also includes the source organization ID for the organization that created the object states package.
    See Starting a loadState job.
  3. 3Send a loadState GET request to get the status of the job. You can also request status at the object level.
    4. Informatica Intelligent Cloud Services returns the status of the job and if requested, status of each object in the package.
    See Getting the loadState job status.

Uploading an object states package

Use a POST request to upload an object states package.

POST request

To upload the object states package, use the following URI:
/public/core/v3/loadState/package
For Content-Type, use
multipart/form-data
In the request body, include a part with the name of package. For its content, use the object states ZIP file that you want to upload.

POST response

If successful, returns the following information for the loadState job:
Field
Type
Description
jobId
String
ID of the loadState job.
jobStatus
Collection
Status of the package upload.
state
String
Returned in the status object.
Status of the loadState job, such as IN PROGRESS, SUCCESS, or FAILED.
message
String
Returned in the status object.
Job status message.
checksumValid
Boolean
Indicates whether the object states package has valid checksum.

POST response example

You might receive a response similar to the following example:
{
"jobId": "hUV9Uq1cKYtf8niqF09CWC",
"jobStatus": {
"state": "NOT_STARTED",
"message": null
},
"checksumValid": true
}

Starting a loadState job

Use a POST request to specify and start a loadState job.

POST request

To specify the objects and start the loadState job, use the following URI:
/public/core/v3/loadState/<id>
The <id> is the loadState job ID received in the POST response for the object states package upload.
Include the following fields in the request:
Field
Type
Required
Description
name
String
Name of the loadState job.
Default name is job-<currentTimeInMilliseconds>
importSpecification
Complex type
Used to specify the objects to include.
includeObjects
Collection<String>
Include in the importSpecification object.
Objects to load.
If not specified, the load includes all states in the object states package.
If the specified object is a project, the load includes state of all objects that belong to the project and all dependent objects.
objectSpecification
Collection <complex type>
Include in the importSpecification object.
Specifies the object properties.
sourceObjectId
String
Yes
Include in the objectSpecification object.
The container ID in the object states package file.
Required if objectSpecification is present.
targetObjectId
String
Yes
Include in the objectSpecification object.
Used for Container to Container mapping.
Required if objectSpecification is present.

POST request example

You might use a request similar to the following example:
POST <baseApiUrl>/public/core/v3/loadState/2oZb7vFI2QQg4ncd4AyCGn HTTP/1.0
Content-Type: application/json
Accept: application/json
INFA-SESSION-ID: <sessionId>

{
"name" : "stateImportJob",
"importSpecification" : {
"includeObjects" : ["iIVBNZSpUKFg4N6g2PKUox","ejZY66c19YUccBdbGwKG4P"],
"objectSpecification" : [{
"sourceObjectId" : "iIVBNZSpUKFg4N6g2PKUox"
},
{
"sourceObjectId" : "5FA0DnMzeuDbYZnn3hdto9",
"targetObjectId" : "5KgUiEkW95NkjLRRefWKiG"
}]
}
}

POST response

If successful, returns the following information for the loadState job:
Field
Type
Description
Id
String
ID of the loadState job.
createTime
String
Time the loadState job was created.
updateTime
String
Last time the loadState job was updated.
name
String
Name of the loadState job.
startTime
String
Start time of the loadState job.
endTime
String
End time of the loadState job.
status
Collection
Status of the package upload.
state
String
Returned in the status object.
Load state for each individual object, such as IN PROGRESS, SUCCESS, FAILED, or SKIPPED.
message
String
Returned in the status object.
Job status message.
objects
Collection
Objects included in the loadState job and object level status.
sourceOrgId
String
Organization ID of the organization that created the object states package.
checksumValid
Boolean
Indicates whether the import package has valid checksum.

POST response examples

If successful, you might receive a response similar to the following example:
{
"id": "a7oaBNCyc8DdhxQD4mY4ul",
"createTime": "2019-01-10T01:35:45.000Z",
"updateTime": "2019-01-10T21:08:41.398Z",
"name": "job-1547154520680",
"startTime": "2019-01-10T21:08:41.389Z",
"endTime": null,
"status": {
"state": "IN_PROGRESS",
"message": "In Progress"
},
"objects": null,
"sourceOrgId": "2wy21a5fkUphzTVNKaPowg",
"checksumValid": true
}
If you receive an error, you might see a response similar to the following example:
{
"error": {
"message": "Import request with identifier [a7oaBNCyc8DdhxQD4mY4u] doesnt exist.",
"requestId": "9MopwrDFAOGbuMM9utiTqJ"
}
}

Getting the loadState job status

Use a GET request to get the status of a loadState job.

GET request

To get status of the loadState job, use one of the following URIs, where <id> is the loadState job ID:

GET response

A request for status returns the following import status information:
Field
Type
Description
id
String
ID of the loadState job.
createTime
String
Time the object states package was created.
updateTime
String
Last time the object states package was updated.
name
String
Name of the loadState job.
startTime
String
Start time of the loadState job.
endTime
String
End time of the loadState job.
status
Complex type
Status of the package upload.
state
String
Returned in the status object.
Status of the loadState job, such as IN PROGRESS, SUCCESS, or FAILED.
message
String
Returned in the status object.
Job status message.
sourceOrgId
String
ID of the organization that created the object states package.
objects
Collection
Objects included in the import.
sourceObject
Collection
Returned in the objects object.
Object included in the import.
id
String
Returned in the objects.sourceObject object.
Global unique identifier for the object included in the import.
name
String
Returned in the objects.sourceObject object.
Name of the object included in the import.
path
String
Returned in the objects.sourceObject object.
Complete path of the object included in the import.
type
String
Returned in the objects.sourceObject object.
Type of object included in the import.
description
String
Returned in the objects.sourceObject object.
Description of the object included in the import.
targetObject
Collection
Returned in the objects object.
Target object.
id
String
Returned in the objects.targetObject object.
Global unique identifier for the target object.
name
String
Returned in the objects.targetObject object.
Name of the target object.
path
String
Returned in the objects.targetObject object.
Complete path of the target object.
type
String
Returned in the objects.targetObject object.
Type of target object.
description
String
Returned in the objects.targetObject object.
Description of target object.
status
String
Returned in the objects.targetObject object.
Status of the target object.
status
Complex type
Returned in the objects object.
Load status of the object.
state
String
Returned in the objects.status object.
Load state of the object, such as IN PROGRESS, SUCCESS, or FAILED.
message
String
Returned in the objects.status object.
Status message for the object.
checksumValid
Boolean
Returned in the objects.status object.
Whether the checksum of the object was valid or not.

GET response example

If your request for a loadState job's status is successful, you might receive a response similar to the following example:
{
"id": "2oZb7vFI2QQg4ncd4AyCGn",
"createTime": "2017-10-26T08:40:09.000Z",
"updateTime": "2017-10-26T08:55:56.000Z",
"name": "stateImportJob",
"startTime": "2017-10-26T08:55:53.000Z",
"endTime": "2017-10-26T08:55:56.000Z",
"status": {
"state": "SUCCESSFUL",
"message": "Import completed successfully."
},
"objects": null,
"sourceOrgId": "2wy21a5fkUphzTVNKaPowg",
"checksumValid": true
}
If your request included load status for individual objects, a successful response might be similar to the following example:
{
"id": "3OpbyDU36UgkUhXXtvGsYA",
"createTime": "2019-01-10T21:35:33.000Z",
"updateTime": "2019-01-10T21:35:39.000Z",
"name": "job-1547156138681",
"startTime": "2019-01-10T21:35:39.000Z",
"endTime": "2019-01-10T21:35:39.000Z",
"status": {
"state": "SUCCESSFUL",
"message": "Import completed successfully."
},
"objects": [
{
"sourceObject": {
"id": "46MhQv9oxrgbOD6qtosF8t",
"name": "MappingTask",
"path": "/Default",
"type": "MTT",
"description": ""
},
"targetObject": {
"id": null,
"name": "MappingTask",
"path": "/Default",
"type": "MTT",
"description": null,
"status": null
},
"status": {
"state": "SUCCESSFUL",
"message": "Overwrite existing."
}
}
],
"sourceOrgId": "2wy21a5fkUphzTVNKaPowg",
"checksumValid": true
}