Automate deployment

Introduction to deployment automation

Since all deployment jobs are performed by Indicium, it is possible to automate the entire process. You can find the run jobs in the Software Factory menu Maintenance > Jobs.

warning

For deployment automation, use the Indicium instance running on the IAM facilitating the Software Factory.

Get the current job status

To obtain the current job status (field job_status) of a given job:

GET [indicium]/iam/sf/job([job_id])

Possible values of the job_status:

Value	Description
0	Queued
1	Pending (to be picked up by Indicium)
2	Active
3	Completed
4	Failed
5	Canceled
6	Aborted

Automate the Creation process

This chapter describes how to automate the complete Creation process or its separate steps.

For more information on the Creation process and how to run it in the user interface, see Creation.

Wait for a Creation step to finish

All Creation jobs return the (last) created job_id through an output parameter.

The wait for job procedure specifies that a Creation process waits until a specific job has been completed before continuing execution. Once that job has finished, the procedure will end automatically.

Use the following parameter:

• job_id - The (integer) id of the job that has to be completed before continuing (123 is an example).

Sample request:

POST [indicium]/iam/sf/wait_for_job

{
    "job_id": 123
}

Automate the complete Creation process

It is possible to execute the complete Creation process at once via the API.

Use the following parameters to call add_job_to_do_complete_creation:

• project_id - The ID of the project you want to create the deployment package for.

• project_vrs_id - The project's version ID.

• execute_complete_creation - When set to 1, all steps will be executed. Set to 0 to enable manual selection of Creation steps.

• Available Creation steps:

  • generate_definition - true or false.
  • validate_definition - true or false.
  • generate_source_code - true or false.
  • execute_source_code - true or false.
  • execute_unit_tests - true or false.

• upgrade_method - For Generate source code, 0 = smart or 1 = full. See Generation method.

• runtime_configuration_id - Code execution and unit test execution will both be done on the provided runtime configuration. Note that this has to be the exact name of the runtime configuration as configured in the Software Factory. You cannot use an application id or application alias.

• generate_definition_error_handling and execute_source_code_error_handling values are:

  Error	Description
  0	Pause and await user input.
  1	Skip the control procedure in error and continue.
  2	Abort generate definition.

• validation_result_creation - How the validation results should affect the further steps:

  Result	Description
  0	Abort on errors.
  1	Abort on warnings.
  2	Abort on any validation message.
  3	Always continue the subsequent Creation steps.

Sample request:

POST [indicium]/iam/sf/add_job_to_do_complete_creation

{
    "project_id": "MY_PROJECT", 
    "project_vrs_id": "1.12",
    "execute_complete_creation": 0,
    "generate_definition": true,
    "validate_definition": true,
    "generate_source_code": true,
    "execute_source_code": true,
    "execute_unit_tests": true,
    "generate_definition_error_handling": 1,
    "validation_result_creation": 3,
    "upgrade_method": 0,
    "runtime_configuration_id": "default",
    "execute_source_code_error_handling": 1
}

Automate 'Generate definition'

Use the following parameters to call add_job_to_generate_definition:

• project_id - The ID of the project for which you want to generate the definitions.

• project_vrs_id - The project's version ID.

• error_handling - Allows the caller to configure what happens when a control procedure fails to execute properly while the definition is generated. The following options are available:

  Error handling	Description
  0	Pause and await user input.
  1	Skip the control procedure in error and continue.
  2	Abort Generate definition.

Sample request:

POST [indicium]/iam/sf/add_job_to_generate_definition

{
    "project_id": "MY_PROJECT", 
    "project_vrs_id": "1.12", 
    "error_handling": 1
}

Automate 'Validate definition'

Use the following parameters to call add_job_to_validate_all:

• project_id - The ID of the project for which you want to validate the definition.
• project_vrs_id - The project's version ID.

POST [indicium]/iam/sf/add_job_to_validate_all

{
    "project_id": "MY_PROJECT", 
    "project_vrs_id": "1.12"
}

Automate 'Generate source code'

Use the following parameters to call add_job_to_generate_code:

• project_id - The ID of the project for which you want to generate the source code.
• project_vrs_id - The project's version ID.
• upgrade_method - 0 = smart or 1 = full. See Generation method.
• write_code_files_to_disk - Write code files to disk, 0 = no or 1 = yes.
• write_prog_objects_to_disk - Write progam objects to disk, 0 = no or 1 = yes.
• store_offline_logic - Rarely used. Only for program objects containing code groups with JavaScript, 0 = no or 1 = yes.

Sample request:

POST [indicium]/iam/sf/add_job_to_generate_code

{
    "project_id": "MY_PROJECT", 
    "project_vrs_id": "1.12",
    "upgrade_method": 0
}

Automate 'Source code execution'

Use the following parameters to call add_job_to_execute_source_code or connect_to_db:

• project_id - The ID of the project for which you want to execute the source code.

• project_vrs_id - The project's version ID.

• runtime_configuration_id - The target for the source code execution. Note that this has to be the exact name of the runtime configuration as configured in the Software Factory. You cannot use an application id or application alias.

• error_handling - What happens when a control procedure fails to execute properly while the code files are executed. The following options are available:

  Error handling	Description
  0	Abort the code execution.
  1	Ignore the current code file and resume execution from the next code file.
  2	Retry the current code file and resume execution from the next statement after the error occurred.
  3	Suspend the code execution and wait for user input.

Sample request:

POST [indicium]/iam/sf/add_job_to_execute_source_code

Or, to start the Source code execution job using Connect:

POST [indicium]/iam/sf/connect_to_db

For both options:

{
    "project_id": "MY_PROJECT", 
    "project_vrs_id": "1.12",
    "runtime_configuration_id": "default",
    "error_handling": 1
}

Automate 'Unit test execution'

Use the following parameters to call add_job_to_test_unit_test (all unit tests). Inactive unit tests will not be executed.

• project_id - The ID of the project for which you want to execute the unit tests.
• project_vrs_id - The project's version ID.
• runtime_configuration_id - The target for the source code execution. Note that this has to be the exact name of the runtime configuration as configured in the Software Factory. You cannot use an application id or application alias.

Sample request:

POST [indicium]/iam/sf/add_job_to_test_unit_test

{
    "project_id": "MY_PROJECT", 
    "project_vrs_id": "1.12",
    "runtime_configuration_id": "default"
}

Automate Synchronization to IAM

This chapter describes how to automate the synchronization to IAM.

For more information on the Synchronization process and how to run it in the user interface, see Synchronization to IAM.

Generate synchronization scripts

Generating synchronization scripts is a prerequisite for synchronizing to either IAM or disk.

Use the following parameters to call add_job_to_generate_sync_script:

• project_id - The ID of the project for which you want to generate the synchronization scripts.

• project_vrs_id - The project's version ID.

• verify- Verify whether changes have been made to an object that has already been synchronized, 1 = yes, 0 = no. See also Verify synchronization.

• sync_all_modules - Only if a project includes modules, select if all modules should be included, 1 = yes, 0 = no.

• deployment_modules - Only if a project includes modules, select if you wish to include a collection of modules.

  For example:

  <deployment_module_id>Module1</deployment_module_id><deployment_module_id>Module2</deployment_module_id><deployment_module_id>Module3</deployment_module_id>
  • If you select a collection of modules, set parameter sync_all_modules to 0.
  • If this parameter is empty and sync_all_modules equals 0, then the last configuration of modules will be used.

Sample request:

POST [indicium]/iam/sf/add_job_to_generate_sync_script

{
    "project_id": "MY_PROJECT", 
    "project_vrs_id": "1.12",
    "verify": 1,
    "sync_all_modules": 1,
    "deployment_modules": null
}

Automate task Synchronize to IAM

After generating the synchronization scripts as described above, you can start the synchronization to IAM:

Use the following parameters to call add_job_to_sync_to_iam:

• project_id - The ID of the project you want to synchronize to IAM.
• project_vrs_id - The project's version ID.
• sync_target_iam_id - Requires the unique identifier of the IAM configuration.

POST [indicium]/iam/sf/add_job_to_sync_to_iam

{
    "project_id": "MY_PROJECT", 
    "project_vrs_id": "1.12",
    "sync_target_iam_id": 1
}

Automate task Synchronization to disk

After generating the synchronization scripts as described above, you can start the synchronization to disk.

Use the following parameters to call add_job_to_sync_to_disk:

• project_id - The ID of the project you want to synchronize to disk.
• project_vrs_id - The project's version ID.
• deployment_package - Decides if the job is used for a deployment package and therefore written to the Deploy folder instead of the root of the project specification folder, 1 = yes, 0 = no.

Sample request:

POST [indicium]/iam/sf/add_job_to_sync_to_disk

{
    "project_id": "MY_PROJECT", 
    "project_vrs_id": "1.12",
    "deployment_package": 0
}

Automate the creation of a deployment package

Use the following parameters to call the task_start_deployment_package:

• project_id - The ID of the project you want to create the deployment package for.
• project_vrs_id - The project's version ID.
• upgrade_method - Smart (0) or Full (1). See Generation method.
• verify - To verify your model while creating the deployment package, yes (1) or no (0).
• deployment_note - Optional. The reason why you create the deployment package.

Sample request:

POST [indicium]/iam/sf/start_deployment_package

{
    "project_id": "MY_PROJECT", 
    "project_vrs_id": "1.12",
    "upgrade_method": 0,
    "verify": 1,
    "deployment_note": "The reason why you create the deployment package."
}

Responses

Deployment automation calls only queue the job and respond with a 200 - OK directly after. Only when you start the synchronization via the API, the created job_id is returned.