Execute an Enterprise Journals Job

This API will execute the job based on the job type provided as a JSON parameter. It is an asynchronous API. This API will respond with a callback API to get the Job status.

Table 21-4 Enterprise Journals Supported Job Types

Job Type Description

exportEJJournals

This job exports the data of "Ready To Validate" or "Ready to Post" journals based on the operation defined. It creates one CSV file per journal based on the target definition and mappings defined in Enterprise Journals and copies it to an EPM Automate-designated directory. The resulting file follows the naming pattern: <Year>_<Period>_<Journal_ID>.csv. After creating the export file, it updates the journal Post status to "Post in Progress" if operation is "posting" or updated the validation status to "Validation In Progress" if operation is "validation".

setEJJournalStatus

This job updates the Post status or Validation status of a journal after importing the journal to the ERP system.

If operation = posting:

A CSV file containing the results of the journal posting is provided. The file contains these columns: Year, Period, Journal ID, Posting Status (Posted/Failed), Message, Error Code, Error Message. The Message, Error Code and Error Message columns are optional. Posting status of the journals is updated based on the status provided in the file. Only journals with a Posting status of "Post in Progress" will be updated.

If operation = validation:

A CSV file containing the results of the journal validation is provided. The file contains these columns: Year, Period, Journal ID, Validation Status (Valid/Failed), Message, Error Code, Error Message. The Message, Error Code and Error Message columns are optional. Validation status of the journals is updated based on the status provided in the file. Only journals with a Validation status of "Validation In Progress" will be updated.

deployEJTemplates

This job is used to deploy finalized journal templates to new journal periods to create journals for year-period combinations, ensuring a consistent and repeatable journal collection process.

REST Resource

POST /HyperionPlanning/rest/ej/{api_version}/jobs

Required Roles

Job Type Role
exportEJJournals Service Administrator
setEJJournalStatus Service Administrator
deployEJTemplates Service Administrator, Power User

Request

Supported Media Types: application/json

Parameters

This table summarizes the request parameters that are generic to all jobs. The following tables describe parameters specific to individual rules.

Table 21-5 Parameters

Name Description Type Required Default
api_version

Version of the API you are developing with

Path

Yes

None

Table 21-6 exportEJJournals Parameters

Name Description Type Required Default
jobType

Type of the Job. Value for this job is exportEJJournals.

String

Yes

None

filename

The name of the zip file to which each individual journal file is added

String

Yes

None

year

The year for which the journal is used for data collection

String

No

None

period

The period for which the journal is used for data collection

String

No

None

operation Specifies the operation - posting or validation

String

No

posting

Table 21-7 setEJJournalStatus Parameters

Name Description Type Required Default
jobType

Type of the Job. Value for this job is setEJJournalStatus.

String

Yes

None

filename

Filename is the file in CSV format that contains the following information regarding the posting process:

  • Year: Year of the Journal posted

  • Period: Period of the Journal posted

  • JournalID: Journal Identifier of Journal posted

  • Posting Status: Valid values are Posted or Failed. (if operation = posting)

  • Validation Status: Valid values are Valid or Failed. (if operation = validation)

    Failed status has a message and attached error list returned from ERP

  • Message: Optional. Can be used for error messages from ERP in case there is a posting failure

Note: Multiple Journal Posting statuses may be included as records in the CSV file.

String

Yes

None

operation Specifies the operation. posting or validation

String

No

posting

Table 21-8 deployEJTemplates Parameters

Name Description Type Required Default
jobType

Type of the Job. Value for this job is EJ_DEPLOY_TEMPLATES

String

Yes

None

year

The year used for the journal

String

Yes

None

period

The period for the journal

String

Yes

None

Template

Names of journal templates that need to be deployed.

You can specify multiple parameters with the same key as "TEMPLATE" in the command, and it will be converted into JSON array and passed as a single parameter in JSON string. If you only specify one template name, it is still passed as JSON array.

This parameter is optional. If no value is specified in the command for the TEMPLATE key, then this parameter would still be present as an empty JSON array in JSON string, and all templates for the specified year and period will be deployed.

JSON Array

No

None

ResetJournals

Value values: True or False.

Optional. Indicates whether or not all journals need to be reset to the first stage after re-deployment.

This parameter is also derived by the system based on changes to the template. The system-derived value can override the user-specified value.

Boolean

No

False

Examples of Request Body

Example for Job Type: exportEJJournals

Example 1:

{
 "jobType" : "exportEJJournals",
 "parameters": {
                              "Filename":"export.zip",
                              "Year":"2020"
                              "Period":"Jan"
                              "Operation":"validation"
                              }
}

Example 2:

{
 "jobType" : "exportEJJournals",
 "parameters": {
                              "Filename":"export.zip",
                              }
}

Example for Job Type: setEJJournalStatus

{
 "jobType" : "setEJJournalStatus",
 "parameters": {
                              "Filename":"JournalsStatus.csv",
                              "Operation":"validation"
                              }
}

Examples for Job Type: deployEJTemplates

Example 1:

{
 "jobType" : "EJ_DEPLOY_TEMPLATES",
 "parameters": {
                              "Year":"2020"
                              "Period":"July"
                              "Template": ["Template 1","Template 2"],
                              "ResetJournals":"true"
                              }
}

Example 2:

{
 "jobType" : "EJ_DEPLOY_TEMPLATES",
 "parameters": {
                              "Year":"2020"
                              "Period":"July"
                              "Template": ["Template 3"],
                              }
}

Example 3:

{
 "jobType" : "EJ_DEPLOY_TEMPLATES",
 "parameters": {
                              "Year":"2020"
                              "Period":"July"
                              "Template": ["Template 5","Template 6", "Template 7", "Template 8"],
                              }
}

Example 4:

{
 "jobType" : "EJ_DEPLOY_TEMPLATES",
 "parameters": {
                              "Year":"2020"
                              "Period":"July"
                              "Template": [ ]
                              }
}

Response

Supported Media Types: application/json

Table 21-9 Parameters

Name Description
jobId

Enterprise Journals job identifier

descriptiveStatus

Additional details about the status

details

Message to the user. In cases where there are errors, the error details are published.

status
  • -1: In Progress

  • 0: Success

  • 1: Failed

items

Not applicable for this job type

links

Detailed information about the link

rel

Valid value: self

href

Links to API call

action

The HTTP call type

Example of Response Body

The following is an example of the response body in JSON format.

{
  "jobId":14013,
  "details": "In Process",
  "status": -1,
  "links": [
    {
      "rel": "self",
      "href": "https://<BASE-URL>/HyperionPlanning/rest/ej/v1/jobs/14013",
     "action": "GET"
    }
  "error": null,
  "items": [ ],
  "type": EPM
}