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

Cancel all jobs

To be sure that no other jobs are running, you can cancel all jobs for the model and branch before starting the planned job.

Use the following parameters:

• model_id - The ID of the model you want to create the deployment package for.
• branch_id - The branch ID.

Sample request:

POST [indicium]/iam/sf/cancel_all_jobs
{
    "model_id": "MY_PROJECT",
    "branch_id": "MAIN"
}

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).
• show_msg - Shows a message about what went wrong if a job cannot be completed successfully, 0 = no or 1 = yes

Sample request:

POST [indicium]/iam/sf/wait_for_job

{
    "job_id": 123,
    "show_msg": 1
}

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:

• model_id - The ID of the model you want to create the deployment package for.

• branch_id - The branch 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.
  • execute_smoke_test - true or false.

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

• runtime_configuration_id - Code execution, unit test execution and smoke test execution will all 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.

• debug - Relevant during the Generate definition process. Logs when the branch is 'locked' and 'unlocked', and actions taken by the user after a process step has failed.

note

If you use a SQL query to execute this task, remove the host and db_name parameters from the execution query.

Sample request:

POST [indicium]/iam/sf/add_job_to_do_complete_creation

{
    "model_id": "MY_MODEL", 
    "branch_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,
    "debug": 1
}

Automate 'Generate definition'

Use the following parameters to call add_job_to_generate_definition:

• model_id - The ID of the model for which you want to generate the definitions.

• branch_id - The branch 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.

• debug - Logs when the branch is 'locked' and 'unlocked', and actions taken by the user after a process step has failed.

Sample request:

POST [indicium]/iam/sf/add_job_to_generate_definition

{
    "model_id": "MY_MODEL", 
    "branch_id": "1.12", 
    "error_handling": 1,
    "debug": 1
}

Automate 'Validate definition'

Use the following parameters to call add_job_to_validate_all:

• model_id - The ID of the model for which you want to validate the definition.

• branch_id - The branch ID.

• validation_type - Allows execution of specific validation types. Leave empty to execute all validations. The following validation types are available:

  Validation type	Description
  0	Model
  1	Branching
  2	Requirements
  3	Datamodel
  4	User interface
  5	Process flows
  6	Application logic
  7	Documentation
  8	Dynamic model
  9	Validation
  10	Functionality
  11	Generation
  12	Test
  13	All (not: 'all validations', but: validation type 'All)'.
  14	Subroutines
  15	Access control

POST [indicium]/iam/sf/add_job_to_validate_all

{
    "model_id": "MY_MODEL", 
    "branch_id": "1.12",
    "validation_type": null
}

Automate 'Generate source code'

Use the following parameters to call add_job_to_generate_code:

• model_id - The ID of the model for which you want to generate the source code.
• branch_id - The branch ID.
• upgrade_method - 0 = smart or 1 = full. See Generation method.
• write_code_files_to_disk - Write code files to storage, 0 = no or 1 = yes.
• write_prog_objects_to_disk - Write progam objects to storage, 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

{
    "model_id": "MY_MODEL", 
    "branch_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:

• model_id - The ID of the model for which you want to execute the source code.

• branch_id - The branch 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:

{
    "model_id": "MY_MODEL", 
    "branch_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.

• model_id - The ID of the model for which you want to execute the unit tests.
• branch_id - The branch 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

{
    "model_id": "MY_MODEL", 
    "branch_id": "1.12",
    "runtime_configuration_id": "default"
}

Automate 'Smoke test execution'

Use the following parameters to call add_job_to_run_smoke_tests.

• model_id - The ID of the model for which you want to execute the unit tests.
• branch_id - The branch 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_run_smoke_tests
{
    "model_id": "MY_MODEL",
    "branch_id": "1.12",
    "runtime_configuration_id": "default"
}

note

If you use a SQL query to execute this task, remove the host and db_name parameters from the execution query.

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 storage.

Use the following parameters to call add_job_to_generate_sync_script:

• model_id - The ID of the model for which you want to generate the synchronization scripts.

• branch_id - The branch 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 model includes modules, select if all modules should be included, 1 = yes, 0 = no.

• deployment_modules - Only if a model 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

{
    "model_id": "MY_MODEL", 
    "branch_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:

• model_id - The ID of the model you want to synchronize to IAM.
• branch_id - The branch ID.
• sync_target_iam_id - Requires the unique identifier of the IAM configuration.

POST [indicium]/iam/sf/add_job_to_sync_to_iam

{
    "model_id": "MY_MODEL", 
    "branch_id": "1.12",
    "sync_target_iam_id": 1
}

Automate task Synchronize to storage

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

Use the following parameters to call add_job_to_sync_to_disk:

• model_id - The ID of the model you want to synchronize to storage.
• model_vrs_name - Optional. Add the name of the model version to write the synchronization scripts to an alternate path. The scripts will be written to \\server\base_path\model\model_vrs_name instead of ...\branch.
• branch_id - The branch 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 model specification folder, 1 = yes, 0 = no.

Sample request:

POST [indicium]/iam/sf/add_job_to_sync_to_disk

{
    "model_id": "MY_MODEL", 
    "branch_id": "1.12",
    "deployment_package": 0
}

Automate the creation of a deployment package

Use the following parameters to call the task_start_deployment_package:

• model_id - The ID of the model you want to create the deployment package for.
• branch_id - The branch 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

{
    "model_id": "MY_MODEL", 
    "branch_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.