CEGID XRP Ultimate Job Connector

 

This connector allows you to launch and monitor CEGID XRP Ultimate jobs from the command line.

Disclaimer

No support or warranties will be provided by Absyss SAS for this project and associated files. Use is at your own risk.

Absyss SAS cannot be held responsible for damages caused by the use of any files made available in this Github repository.

Consulting days can be requested for implementation.

Prerequisites

• Visual TOM 7.3.2 or higher
• Python 3.x or higher
• CEGID XRP Ultimate API access
• Install required python packages with pip: pip install -r requirements_cegid.txt

Instructions

• Windows :

  • Place the files submit_queue_cegid.bat & cegid.py in the %ABM_BIN% directory
  • Declare the queue on the agent (see administrator guide)

• Linux/Unix :

  • Place the files tom_submit.cegid & cegid.py in the $TOM_ADMIN directory
  • Declare the queue on the agent (see administrator guide)

Create a CEGID Context and define the following environment variables:

Required environment variables

• CEGID_BASE_URL: Base URL of the CEGID API (e.g., https://server/dev/rest/api)
• CEGID_CLIENT_ID: API key ID (CLE_AP_REST)
• CEGID_CLIENT_SECRET: API key secret (SECRET_CLE_API_REST)

Optional environment variables

Basic configuration

• CEGID_TOKEN_URL: Token URL (default: {CEGID_BASE_URL}/rest/security/authentication)
• CEGID_EXEC_TYPE: Execution type (default: "E")
• CEGID_MAX_TIME_WAIT: Maximum wait time in seconds (default: 0 = no limit)
• CEGID_AUTH_HEADER_TYPE: Authentication header type — "qualiac" or "bearer" (default: "qualiac")

Job configuration

• CEGID_JOB_MNEMONIC: Job mnemonic (can be passed as parameter %1)
• CEGID_WAIT_FOR_RESULT: Wait for job completion — "true" or "false" (default: "true")
• CEGID_POLL_INTERVAL_SEC: Polling interval in seconds (default: 5)
• CEGID_POLL_TIMEOUT_SEC: Polling timeout in seconds (default: 900 = 15 minutes)
• CEGID_JOB_PARAMS: Job parameters as JSON string (e.g., '{"param1":"value1","param2":"123"}')

Endpoint configuration (advanced)

• CEGID_RUN_ENDPOINT: Endpoint to launch a job (default: {CEGID_BASE_URL}/foundations/jobs)
• CEGID_JOBS_INFORMATION_ENDPOINT_TMPL: Template for detailed status endpoint (default: {base}/foundations/jobsInformation/{jobNumber})
• CEGID_JOB_STATUS_ENDPOINT_TMPL: Template for simple status endpoint (default: {base}/foundations/jobStatus/{jobNumber})
• CEGID_STATUS_ENDPOINT_TMPL: Template for status endpoint (backward compatibility, default: same as CEGID_JOBS_INFORMATION_ENDPOINT_TMPL)

Result file configuration

• CEGID_JOB_FILE_RESULT_ENDPOINT_TMPL: Template for file result endpoint (default: {base}/foundations/jobFileResult/{jobNumber})
• CEGID_JOB_FILE_RESULT_TYPE: Type of file to retrieve (default: "JOB_FILE_RESULT")
  • Possible values: JOB_FILE_RESULT, JOB_FILE_RESULT_PDF, JOB_FILE_RESULT_ASCII, JOB_FILE, JOB_FILE_ERROR
• CEGID_JOB_FILE_RESULT_DIR: Directory where to save result files (default: ".")
• CEGID_JOB_FILE_RESULT_ENABLED: Enable automatic result file retrieval — "true" or "false" (default: "true")

File retrieval behavior

• If status == "T":
  • The script attempts to download the file using CEGID_JOB_FILE_RESULT_TYPE.
  • If status1 is present, it still attempts the download, then fails (RuntimeError).
• If status == "S":
  • The script forces error-file retrieval with type=JOB_FILE_ERROR.
  • Then it fails (RuntimeError).
• The fileName sent to the API is always the short filename (basename), never a full path returned by the API.

Display configuration

• CEGID_PAYLOAD_FIELDS: Payload fields to display, comma-separated (default: "jobNumber,status,status1,totalDuration,resultFile,pDFFile,dataFile")
  • Use "*" to display all fields

Important note about JSON parameters:

• All numeric values are automatically converted to strings
• Keys can contain special characters like > (e.g., "10>EDTTRT")
• Accepted format: '{"10>EDTTRT":"O","DCRD":"20250305"}' or '{10>EDTTRT:O,DCRD:20250305}' (will be automatically corrected)
• Booleans (true/false) and null remain native JSON values

Create a "Custom Application" connection in Visual TOM with the following definition or import the CEGID.xml file:

vtimport -x -f CEGID.xml

The script returns specific exit codes:

• 0: Success
• 1: Error (connection, validation, or execution error)
• 2: Configuration error (missing required environment variables or invalid parameters)

Parameter description:

• MNEMONIC: CEGID job mnemonic (required for job launch)
• WAIT_FOR_RESULT: Wait for job completion — "true" or "false" (default: "true")
• POLL_INTERVAL_SEC: Polling interval in seconds (default: 5)
• POLL_TIMEOUT_SEC: Polling timeout in seconds (default: 900)
• JOB_PARAMS: Job parameters as JSON string (optional, e.g., '{"10>EDTTRT":"O","DCRD":"20250305"}')

The connector provides detailed logging with:

• Timestamps
• Log levels (INFO, WARNING, ERROR)
• Detailed operation status (authentication, launch, polling, file retrieval)
• Job state information

Example log output:

2025-10-22 14:27:30,797 | INFO | Retrieving token from: https://server/dev/rest/api/rest/security/authentication
2025-10-22 14:27:30,850 | INFO | Token retrieved successfully
2025-10-22 14:27:30,851 | INFO | Launching job: MY_JOB
2025-10-22 14:27:30,857 | INFO | URL used to launch job: https://server/dev/rest/api/foundations/jobs
2025-10-22 14:27:35,120 | INFO | Waiting 5 seconds before retrieving result file...

Available actions

Job launch with wait

Action: Run (default mode, WAIT_FOR_RESULT=true)

Parameters: MNEMONIC (required), WAIT_FOR_RESULT, POLL_INTERVAL_SEC, POLL_TIMEOUT_SEC, JOB_PARAMS (optional)

Description: Launches a CEGID job, waits for completion, and optionally retrieves the result file

Asynchronous job launch

Action: Run (WAIT_FOR_RESULT=false)

Parameters: MNEMONIC (required), JOB_PARAMS (optional)

Description: Launches a job and immediately returns the execution number (executionId) for later status checking

Status check

Action: Status

Parameters: job_number (required — job number returned at launch)

Description: Checks the status of an existing job without launching a new one

Example:

python cegid.py status "12345"

Result file management

Action: Automatic on job completion (if CEGID_JOB_FILE_RESULT_ENABLED=true)

Parameters: CEGID_JOB_FILE_RESULT_TYPE (optional — file type: JOB_FILE_RESULT, JOB_FILE_RESULT_PDF, JOB_FILE_ERROR, etc.)

Description: Downloads the result or error file according to the final job status (T = completed, S = error)