AWS Mainframe Modernization Service (Managed Runtime Environment experience) is no longer open to new customers. For capabilities similar to AWS Mainframe Modernization Service (Managed Runtime Environment experience) explore AWS Mainframe Modernization Service (Self-Managed Experience). Existing customers can continue to use the service as normal. For more information, see [AWS Mainframe Modernization availability change](https://docs.aws.amazon.com/m2/latest/userguide/mainframe-modernization-availability-change.html).

# AWS Transform for mainframe Runtime APIs
<a name="ba-runtime-endpoints"></a>

The AWS Transform for mainframe Runtime uses several web-applications to expose REST endpoints, providing ways to interact with the modernized applications using REST clients (e.g. calling jobs using a scheduler).

The purpose of this document is to list available REST endpoints, giving details about:
+ Their role
+ The way to use them properly 

The endpoints listing is organized into categories, depending on the nature of the provided service and the web-application exposing the endpoints.

We assume that you already have a basic knowledge of using REST endpoints using dedicated tools such as [POSTMAN](https://www.postman.com/), [Thunder Client](https://www.thunderclient.com/), [CURL](https://curl.se/), web browsers, etc ...) or writing your own piece of code to make an API call.

**Topics**
+ [Available endpoints for user when building URLs](ba-endpoints-build-urls.md)
+ [Endpoints for Gapwalk application in AWS Transform for mainframe](ba-endpoints-gapwalk.md)
+ [Blusam application console REST endpoints](ba-endpoints-bac.md)
+ [Manage JICS application console in AWS Transform for mainframe](ba-endpoints-jac.md)
+ [Data structures for AWS Transform for mainframe user](ba-endpoints-apx.md)

# Available endpoints for user when building URLs
<a name="ba-endpoints-build-urls"></a>

This topic lists the URLs with root paths for endpoints. Each web application below is defining a **root path**, shared by all endpoints. **Each endpoint then adds its own dedicated path**. The resulting URL to use is the result of the concatenation of the paths. For instance, considering the first endpoint for the Gapwalk application, we have:
+ `/gapwalk-application` for the root web-application path.
+ `/scripts` for the dedicated endpoint path.

The resulting URL to use will be `http://server:port/gapwalk-application/scripts`

**server**  
points at the server name (the one hosting the given web-application).

**port**  
the port exposed by the server.

# Endpoints for Gapwalk application in AWS Transform for mainframe
<a name="ba-endpoints-gapwalk"></a>

In this topic, learn about the endpoints for the Gapwalk web application. These use the root path `/gapwalk-application`.

**Topics**
+ [Batch jobs (modernized JCLs and alike) related endpoints](#ba-endpoints-gapwalk-batch)
+ [Metrics endpoints](#ba-endpoints-gapwalk-metrics)
+ [Other endpoints](#ba-endpoints-gapwalk-other)
+ [Job queues related endpoints](#ba-endpoints-gapwalk-jobq)

## Batch jobs (modernized JCLs and alike) related endpoints
<a name="ba-endpoints-gapwalk-batch"></a>

Batch jobs can be run either synchronously or asynchronously (see details below). Batch jobs are being executed using groovy scripts that are the results of the modernization of legacy scripts (JCL).

**Topics**
+ [List deployed scripts](#ba-list-deployed-scripts)
+ [Launch a script synchronously](#ba-launch-script-synchronously)
+ [Launch a script asynchronously](#ba-launch-script-asynchronously)
+ [Listing triggered scripts](#ba-launch-script-triggered)
+ [Retrieving job execution details](#ba-retrieve-job-execution-details)
+ [Listing asynchronously launched scripts that can be killed](#ba-list-async-scripts)
+ [Listing synchronously launched scripts that can be killed](#ba-list-sync-scripts)
+ [Killing a given job execution](#ba-kill-job-execution)
+ [Listing existing checkpoints for restartability](#ba-list-existing-checkpoints)
+ [Restarting a job (synchronously)](#ba-restart-job-sync)
+ [Restarting a job (asynchronously)](#ba-restart-job-async)
+ [Setting thread limit for asynchronous job executions](#ba-set-thread-limit)

### List deployed scripts
<a name="ba-list-deployed-scripts"></a>
+ Supported method: GET

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/scripts`
+ Arguments: none
+ This endpoint returns the list of deployed groovy scripts on the server, as a String. This endpoint is primarily intended to be used from a web browser, since the resulting String is a HTML page, with active links (a link per launchable script -- see sample below).

Sample response:

```
<p><a href=./script/COMBTRAN>COMBTRAN</a></p><p><a href=./script/CREASTMT>CREASTMT</a></p><p><a href=./script/INTCALC>INTCALC</a></p><p><a href=./script/POSTTRAN>POSTTRAN</a></p><p><a href=./script/REPROC>REPROC</a></p><p><a href=./script/TRANBKP>TRANBKP</a></p><p><a href=./script/TRANREPT>TRANREPT</a></p><p><a href=./script/functions>functions</a></p>
```

**Note**  
The links represent the url to use to launch each listed script **synchronously**.
+ Supported method: GET / POST

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/triggerscripts`
+ Arguments: none
+ This endpoint returns the list of deployed groovy scripts on the server, as a String. This endpoint is primarily intended to be used from a web browser, since the resulting String is a HTML page, with active links (a link per launch-able script -- see sample below).

  As opposed to the previous endpoint response, the links represent the url to use to launch each listed script **asynchronously**.  
![\[Listing scripts sample (browser view)\]](http://docs.aws.amazon.com/m2/latest/userguide/images/trigger_scripts.png)

### Launch a script synchronously
<a name="ba-launch-script-synchronously"></a>

This endpoint has two variants with dedicated paths for GET and POST usage (see below).
+ Supported method: GET

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/script/{scriptId:.+}`
+ Supported method: POST

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/post/script/{scriptId:.+}`
+ Arguments:
  + identifier of the script to launch **Input validation**: Script ID must not be blank, cannot exceed 255 characters, and must match the pattern: `^[a-zA-Z0-9._-]+$`
  + optionally: parameters to pass to the script, using request parameters (seen as a `Map<String,String>`). The given parameters will be automatically added to the [bindings](https://docs.groovy-lang.org/latest/html/api/groovy/lang/Binding.html) of the invoked groovy script. **Input validation**: Parameter map cannot exceed 50 entries.
+ The call executes the script (identified by scriptId) with optional parameters and waits for completion before returning a *ResponseEntityString* with either: 
  + HTTP 200: "Done." or JSON success message on successful execution
  + HTTP 200: A JSON error message with execution failure details. Additional information available in server logs.
**Note**  
Runtime now supports returning HTTP 500 status code for failed job executions. See [Available properties for the main application](https://docs.aws.amazon.com/m2/latest/userguide/ba-runtime-key-value.html#ba-runtime-key-value-main) to configure this response code.
  + **Input Validation**: Invalid script ID or parameters will return HTTP 400 Bad Request with validation error details.

    ```
    {
        "exitCode": -1,
        "stepName": "STEP15",
        "program": "CBACT04C",
        "status": "Error"
    }
    ```

    Looking at the server logs, we can figure out that this a deployment issue (the expected program has not been properly deployed, so it cannot be found, making job execution fail):  
![\[Script execution error sample\]](http://docs.aws.amazon.com/m2/latest/userguide/images/script_exec_error_logs.png)

**Note**  
The synchronous calls should be reserved for short time running jobs. Long times running jobs should rather be launched asynchronously (see dedicated endpoint below).

### Launch a script asynchronously
<a name="ba-launch-script-asynchronously"></a>
+ Supported methods: GET / POST

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/triggerscript/{scriptId:.+}`
+ Arguments:
  + identifier of the script to launch **Input validation**: Script ID must not be blank, cannot exceed 255 characters, and must match the pattern: `^[a-zA-Z0-9._-]+$`
  + optionally: parameters to pass to the script, using request parameters (seen as a `Map<String,String>`). The given parameters will be automatically added to the [bindings](https://docs.groovy-lang.org/latest/html/api/groovy/lang/Binding.html) of the invoked groovy script. **Input validation**: Parameter map cannot exceed 50 entries.
+ As opposed to the synchronous mode above, the endpoint is not waiting for the job execution to finish to send a response. The job execution is launched at once, if an available thread can be found to do so, and a response is sent immediately to caller, with the job execution id, a unique identifier representing the job execution, that can be used to query job execution status or force kill a job execution that is supposed to be malfunctioning. The format of the response is:

  ```
  Triggered script <script identifier> [unique job execution id] @ <date and time>
  ```
+ Since the job asynchronous execution relies on a fixed limited number of threads, the job execution might not be launched if no available thread could be found. In that case, the returned message will rather look like:

  ```
  Script [<script identifier>] NOT triggered - Thread limit reached (<actual thread limit>) - Please retry later or increase thread limit.
  ```

  See the `settriggerthreadlimit` endpoint below to learn how to increase the thread limit.

Sample response:

```
Triggered script INTCALC [d43cbf46-4255-4ce2-aac2-79137573a8b4] @ 06-12-2023 16:26:15
```

The unique job execution identifier permits to quickly retrieve related log entries in the server logs if required. It is also used by several other endpoints detailed below.

### Listing triggered scripts
<a name="ba-launch-script-triggered"></a>
+ Supported methods: GET / POST

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Paths: `/triggeredscripts/{status:.+}`, `/triggeredscripts/{status:.+}/{namefilter}`
+ Arguments:
  + Status (mandatory): the status of the triggered scripts to retrieve. **Input validation**: Status must not be blank and cannot exceed 50 characters. Possibles values are:
    + `all` : show all job execution details, whether the jobs are still running or not.
    + `running`: only show jobs details for jobs that are currently running.
    + `done`: only show jobs details for jobs whose execution is over. 
    + `killed`: only show jobs details for jobs whose execution has been forcefully killed using the dedicated endpoint (see below). 
    + `triggered`: only show jobs details for jobs which have been triggered but not yet launched.
    + `failed`: only show jobs details for jobs whose execution has been marked as failed.
    + \$1namefilter (optional)\$1 : retrieve only executions for the given script identifier. **Input validation**: Cannot exceed 255 characters
+ Returns a collection of job executions details as JSON. For more information, see [Job execution details message structure](ba-endpoints-apx.md#job-execution-details).

Sample response:

```
[
    {
      "scriptId": "INTCALC",
      "caller": "127.0.0.1",
      "identifier": "d43cbf46-4255-4ce2-aac2-79137573a8b4",
      "startTime": "06-12-2023 16:26:15",
      "endTime": "06-12-2023 16:26:15",
      "status": "DONE",
      "executionResult": "{ \"exitCode\": -1, \"stepName\": \"STEP15\", \"program\": \"CBACT04C\", \"status\": \"Error\" }",
      "executionMode": "ASYNCHRONOUS"
    }
  ]
```

### Retrieving job execution details
<a name="ba-retrieve-job-execution-details"></a>
+ Supported method: GET

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/getjobexecutioninfo/{jobexecutionid:.+}`
+ Arguments:
  + jobexecutionid (mandatory): the unique job execution identifier to retrieve the corresponding job execution details. **Input validation**: Job execution ID must not be blank and cannot exceed 255 characters
+ Returns a JSON string representing a single job execution details (see [Job execution details message structure](ba-endpoints-apx.md#job-execution-details)) or an empty response if no job execution details could be found for the given identifier.

### Listing asynchronously launched scripts that can be killed
<a name="ba-list-async-scripts"></a>
+ Supported method: GET

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/killablescripts`
+ Returns a collection of job execution identifiers of jobs which have been launched asynchronously that are still currently running and can be forcefully killed (see the `/kill` endpoint below).

### Listing synchronously launched scripts that can be killed
<a name="ba-list-sync-scripts"></a>
+ Supported method: GET

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/killablesyncscripts`
+ Returns a collection of job execution identifiers of jobs which have been launched synchronously, are still currently running and can be forcefully killed (see the `/kill` endpoint below).

### Killing a given job execution
<a name="ba-kill-job-execution"></a>
+ Supported method: POST

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN
+ Path: `/kill/{identifier:.+}`
+ Argument: job execution identifier (mandatory): the unique job execution identifier to point at the job execution to be forcefully killed. **Input validation**: Identifier must not be blank and cannot exceed 255 characters
+ Returns a textual message detailing the job execution kill attempt outcome; the message will contain the script identifier, the job execution unique identifier and the date and time at which the execution kill occurred. If no running job execution could be found for the given identifier, an error message will be returned instead. 

**Warning**  
 The runtime makes its best effort to kill the target job execution nicely. Thus, the response from the /kill endpoint might take a bit of time to reach the caller, as the AWS Transform for mainframe runtime will try to minimize the business impact of killing the job.
Forcefully killing a job execution should not be done lightly, as it may have direct business consequences, including possible data loss or corruption. It should be reserved for cases where a given job execution has gone sideways and data remediation means are clearly identified.
Killing a job should lead to further investigations (post-mortem analysis) to figure out what went wrong and take proper remediations actions.
In any case, attempt to kill a running job will be logged in the server logs with warning level messages.

### Listing existing checkpoints for restartability
<a name="ba-list-existing-checkpoints"></a>

Job restartability relies on the ability for the scripts to register checkpoints in the `CheckpointRegistry` to track down the job execution progress. If a job execution fails to end properly, and restart checkpoints have been registered, one can simply restart the job execution from the last known registered checkpoint (without having to execute the predecessor steps above the checkpoint).
+ Supported method: POST

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN
+ Path: `/restarts/{scriptId}/{jobId}`
+ Arguments:
  + scriptId (optional - string): the script being restarted.
  + jobId (optional - string): the unique identifier of a job execution.
+ Returns a JSON formatted list of existing restart points, that can be used to restart a job whose execution did not come to and end properly or trigger a delayed restart by bypassing previously executed steps. If no checkpoints were registered by any scripts, the page contents will be "No registered checkpoints".

### Restarting a job (synchronously)
<a name="ba-restart-job-sync"></a>
+ Supported method: POST

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN
+ Path: `/restart/{hashcode}/{scriptId}/{skipflag}`
+ Arguments: 
  + hashcode (integer - mandatory): restart the most recent execution of a job, using the provided hashcode as checkpoint value (see the `/restarts` endpoint above to learn how to retrieve a valid checkpoint value).
  + scriptId (optional - string): the script being restarted.
  + skipflag (optional - boolean): skip execution of selected (checkpoint) step and issue a restart from immediate successor step (if any).
+ Returns: see `/script` return description above.

### Restarting a job (asynchronously)
<a name="ba-restart-job-async"></a>
+ Supported method: GET

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/triggerrestart/{hashcode}/{scriptId}/{skipflag}`
+ Arguments: 
  + hashcode (integer - mandatory): restart the most recent execution of a job, using the provided hashcode as checkpoint value (see the `/restarts` endpoint above to learn how to retrieve a valid checkpoint value).
  + scriptId (optional - string): the script being restarted.
  + skipflag (optional - boolean): skip execution of selected (checkpoint) step and issue a restart from immediate successor step (if any).
+ Returns: see `/triggerscript` return description above.

### Setting thread limit for asynchronous job executions
<a name="ba-set-thread-limit"></a>

The job asynchronous execution relies on a dedicated pool of threads in the JVM. That pool has a fixed limit regarding the number of available threads. The used has the ability to adjust the limit according to the host capabilities (number of CPUs, available memory, etc...). By default, the thread limit is set to 5 threads.
+ Supported method: POST

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN
+ Path: `/settriggerthreadlimit/{threadlimit:.+}`
+ Argument (integer): the new thread limit to apply. **Input validation**: Must be between 1 and 1000 inclusive.
+ Returns a message (`String`) giving the new thread limit and the previous one, or en error message if the provided thread limit value is not valid (not a strictly positive integer).

Sample response:

```
Set thread limit for Script Tower Control to 10 (previous value was 5)
```

#### Counting currently running triggered job executions
<a name="ba-count-current-jobs"></a>
+ Supported method: GET

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/countrunningtriggeredscripts`
+ Returns a message indicating the number of running jobs launched asynchronously and the thread limit (that is the maximum number of triggered jobs that can run simultaneously).

Sample response:

```
0 triggered script(s) running (limit =10)
```

**Note**  
This can be used to check, prior to launching a job, if the thread limit has not been reached (which would prevent the job from being launched). 

#### Purge job executions information
<a name="ba-purge-job-info"></a>

The job executions information remain in the server memory as long as the server is up. It might be convenient to purge oldest informations from the memory, as they are not relevant anymore; this is the purpose of this endpoint.
+ Supported method: POST

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN
+ Path: `/purgejobinformation/{age:.+}`
+ Arguments: a strictly positive integer value representing the age in hours of informations to be purged. **Input validation**: Must be between 0 and 365 inclusive.
+ Returns a message with the following informations:
  + Name of the purge file where purged job execution informations are being stored for archiving purpose.
  + Number of purged job execution informations.
  + Number of remaining job execution informations in memo

## Metrics endpoints
<a name="ba-endpoints-gapwalk-metrics"></a>

**Input validation**: All metrics endpoints validate request parameters and return HTTP 400 Bad Request for invalid values.

### JVM
<a name="ba-metrics-jvm"></a>

This endpoint returns available metrics related to the JVM.
+ Supported method: GET

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/metrics/jvm`
+ Arguments: none
+ Returns a message with the following information:
  + threadActiveCount: Number of active threads.
  + jvmMemoryUsed: Memory actively used by the Java Virtual Machine.
  + jvmMemoryMax: Maximum memory allowed for the Java Virtual Machine.
  + jvmMemoryFree: Available memory not currently in use by the Java Virtual Machine.

### Session
<a name="ba-metrics-session"></a>

This endpoint returns metrics related to currently opened HTTP sessions.
+ Supported method: GET

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/metrics/session`
+ Arguments: none
+ Returns a message with the following information:
  + sessionCount: Number of active user sessions currently maintained by the server.

### Batch
<a name="ba-metrics-batch"></a>
+ Supported method: GET

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/metrics/batch`
+ Arguments:
  + startTimestamp (optional, number): Starting timestamp for data filtering. **Input validation**: Must be a valid numeric value.
  + endTimestamp (optional, number): Ending timestamp for data filtering. **Input validation**: Must be a valid numeric value.
  + page (optional, number): Page number for pagination. **Input validation**: Must be a positive integer.
  + pageSize (optional, number): Number of items per page in pagination. **Input validation**: Must be a strictly positive integer, maximum 500.
  + **Input validation**: Parameter map cannot exceed 20 entries
+ Returns a message with the following information:
  + content: List of batch execution metrics.
  + pageNumber: Current page number in pagination.
  + pageSize: Number of items displayed per page.
  + totalPages: Total number of pages available.
  + numberOfElements: Count of items on the current page.
  + last: Boolean flag for the last page.
  + first: Boolean flag for the first page.

### Transaction
<a name="ba-metrics-transaction"></a>
+ Supported method: GET

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/metrics/transaction`
+ Arguments:
  + startTimestamp (optional, number): Starting timestamp for data filtering. **Input validation**: Must be a valid numeric value.
  + endTimestamp (optional, number): Ending timestamp for data filtering. **Input validation**: Must be a valid numeric value.
  + page (optional, number): Page number for pagination. **Input validation**: Must be a positive integer.
  + pageSize (optional, number): Number of items per page in pagination. **Input validation**: Must be a strictly positive integer, maximum 500.
  + **Input validation**: Parameter map cannot exceed 20 entries
+ Returns a message with the following information:
  + content: List of transaction execution metrics.
  + pageNumber: Current page number in pagination.
  + pageSize: Number of items displayed per page.
  + totalPages: Total number of pages available.
  + numberOfElements: Count of items on the current page.
  + last: Boolean flag for the last page.
  + first: Boolean flag for the first page.

## Other endpoints
<a name="ba-endpoints-gapwalk-other"></a>

Use these endpoints to list list registered programs or services, discover health status, and manage JICS transactions.

**Topics**
+ [Listing registered programs](#ba-list-registered-programs)
+ [Listing registered services](#ba-list-registered-services)
+ [Health status](#ba-health-status)
+ [Listing available JICS transactions](#ba-list-jics-transactions)
+ [Launch a JICS transaction](#ba-launch-jics-transaction)
+ [Launch a JICS transaction (alternative)](#ba-launch-jics-transaction-alt)
+ [List active sessions](#ba-active-session-list)

### Listing registered programs
<a name="ba-list-registered-programs"></a>
+ Supported method: GET

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/programs`
+ Returns the list of registered programs, as a html page. Each program is designated by its main program identifier. Both modernized legacy programs and utility programs (IDCAMS, IEBGENER, etc ...) are being returned in the list. Please note that the available utility programs will depend on the utility web-applications that have been deployed on your tomcat server. For instance, z/OS utility support programs might not be available for modernized iSeries assets, as they are not relevant. 

### Listing registered services
<a name="ba-list-registered-services"></a>
+ Supported method: GET

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/services`
+ Returns the list of registered runtime services, as a html page. The given services are brought by the AWS Transform for mainframe runtime as utilities, that can be used for instance in groovy scripts. Blusam load services (to create Blusam datasets from legacy datasets) fall into that category.

Sample response:

```
<p>BluesamESDSFileLoader</p><p>BluesamKSDSFileLoader</p><p>BluesamRRDSFileLoader</p>
```

### Health status
<a name="ba-health-status"></a>
+ Supported method: GET

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/`
+ Returns a simple message, indicating that the gapwalk-application is up and running (`Jics application is running.`)

### Listing available JICS transactions
<a name="ba-list-jics-transactions"></a>
+ Supported method: GET

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/transactions`
+ Returns a html page listing all available JICS transactions. This only makes sense for environments with JICS elements (modernization of legacy CICS elements).

Sample response:

```
<p>INQ1</p><p>MENU</p><p>MNT2</p><p>ORD1</p><p>PRNT</p>
```

### Launch a JICS transaction
<a name="ba-launch-jics-transaction"></a>
+ Supported methods: POST

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/jicstransrunner/{jtrans:.+}`
+ Arguments:
  + JICS transaction identifier (string, required) : identifier of the JICS transaction to be launched (8 characters long at max.)
  + required: additional input data to pass to the transaction, as a Map<String,Object>. The contents of this map will be used to feed the [COMMAREA](https://www.ibm.com/docs/en/cics-ts/5.4?topic=programs-commarea) that will be consumed by the JICS transaction. The map can be empty if no data is required to run the transaction.
  + optional: Http headers entries, to customize the run environment for the given transaction. The following header keys are being supported:
    + `jics-channel`: The name of the JICS CHANNEL to be used by the program that will be launched by this transaction launch. 
    + `jics-container`: The name of the JICS CONTAINER to be used for this JICS transaction launch.
    + `jics-startcode`: the STARTCODE (String, up to 2 characters) to use at JICS transaction start. See [STARTCODE](https://www.ibm.com/docs/en/cics-ts/5.5?topic=summary-assign) for possible values (browse down the page).
    + `jicxa-xid` : The XID (X/Open transaction identifier XID structure) of a "global transaction" ([XA](https://en.wikipedia.org/wiki/X/Open_XA)), initiated by the caller, to which the current JICS transaction launch will participate. **Input validation**: XID must not be blank and cannot exceed 255 characters.
+ Returns a `com.netfective.bluage.gapwalk.rt.shared.web.TransactionResultBean` JSON serialization, representing the outcome of the JICS transaction launch.
+ **Input validation**: Invalid XID values (blank or exceeding 255 characters) will return HTTP 400 Bad Request with validation error details.

For more information about the details of the structure, see [Transaction launch outcome structure](ba-endpoints-apx.md#transaction-outcome).

### Launch a JICS transaction (alternative)
<a name="ba-launch-jics-transaction-alt"></a>
+ supported methods: POST

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ path: `/jicstransaction/{jtrans:.+}`
+ Arguments:  
**JICS transaction identifier (string, required)**  
identifier of the JICS transaction to be launched (8 characters long at max.)  
**required: additional input data to pass to the transaction, as a Map<String,Object>**  
The contents of this map will be used to feed the [COMMAREA](https://www.ibm.com/docs/en/cics-ts/5.4?topic=programs-commarea) that will be consumed by the JICS transaction. The map can be empty if no data is required to run the transaction.  
**optional: Http headers entries, to customize the run environment for the given transaction.**  
The following header keys are being supported:  
  + `jics-channel`: The name of the JICS CHANNEL to be used by the program that will be launched by this transaction launch. 
  + `jics-container`: The name of the JICS CONTAINER to be used for this JICS transaction launch.
  + `jics-startcode`: the STARTCODE (String, up to 2 characters) to use at JICS transaction start. For possible values, see [STARTCODE](https://www.ibm.com/docs/en/cics-ts/5.5?topic=summary-assign) (browse down the page).
  + `jicxa-xid` : The XID (X/Open transaction identifier XID structure) of a "global transaction" ([XA](https://en.wikipedia.org/wiki/X/Open_XA)), initiated by the caller, to which the current JICS transaction launch will participate. **Input validation**: XID must not be blank and cannot exceed 255 characters.
+ Returns a `com.netfective.bluage.gapwalk.rt.shared.web.RecordHolderBean` JSON serialization, representing the outcome of the JICS transaction launch. The details of the structure can be found in [Transaction launch record outcome structure](ba-endpoints-apx.md#transaction-record-outcome). 
+ **Input validation**: Invalid XID values (blank or exceeding 255 characters) will return HTTP 400 Bad Request with validation error details.

### List active sessions
<a name="ba-active-session-list"></a>
+ supported methods: GET

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN
+ path: `/activesessionlist`
+ Arguments: none
+ **Input validation**: Parameter map cannot exceed 20 entries
+ Returns a list of `com.netfective.bluage.gapwalk.application.web.sessiontracker.SessionTrackerObject` in JSON serialization, representing the list of active user sessions. When session tracking is disabled, an empty list will be returned.

## Job queues related endpoints
<a name="ba-endpoints-gapwalk-jobq"></a>

 Job queues are the AWS Transform for mainframe support for the AS400 jobs submission mechanism. Job queues are used in AS400 to run job on specific thread pools. A job queue is defined by a name and a maximum number of threads that corresponds to the maximum number of programs that can be run simultaneously on that queue. If more jobs are submitted on the queue than the maximum number of threads, jobs will wait for a thread to be available.

For an exhaustive list of status for a job on a queue, see [Possible status of a job on a queue](ba-endpoints-apx.md#jobs-status).

Operations on job queues are handled through the following dedicated endpoints. You can invoke these operations from the Gapwalk Application URL with the following root URL: `http://server:port/gapwalk-application/jobqueue`.

**Topics**
+ [List available queues](#ba-list-available-queues)
+ [Start or restart a job queue](#ba-start-restart-queue)
+ [Submit a job for launch](#ba-submit-job-launch)
+ [List all submitted jobs](#ba-list-scheduled-jobs)
+ [Release all jobs that are "on hold"](#ba-release-held-jobs)
+ [Release all jobs that are "on hold" for a given job name](#ba-release-held-jobs-name)
+ [Release a given job for a job number](#ba-release-job-number)
+ [Submit a job on repeating schedule](#ba-submit-job-on-repeating-schedule)
+ [List all submitted repeating jobs](#ba-list-all-submitted-repeating-jobs)
+ [Cancel the scheduling of a repeating job](#ba-cancel-scheduling-of-repeating-job)

### List available queues
<a name="ba-list-available-queues"></a>
+ Supported method: GET

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `list-queues`
+ Returns the list of available queues along with their status, as a JSON list of key-values.

Sample response:

```
{"Default":"STAND_BY","queue1":"STARTED","queue2":"STARTED"}
```

Possible status for a job queue are:

**STAND\$1BY**  
the job queue is waiting to be started.

**STARTED**  
the job queue is up and running.

**UNKNOWN**  
the job queue status cannot be determined.

### Start or restart a job queue
<a name="ba-start-restart-queue"></a>
+ Supported method: POST

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN
+ Path: `/restart/{name}`
+ Argument: the name of the queue to be started/restarted, as a String - mandatory. **Input validation**: Queue name must not be blank and cannot exceed 255 characters.
+ The endpoint does not return anything but rather relies on http status to indicate the outcome of the start/restart operation:  
**HTTP 200**  
the start/restart operation went well: the given job queue is now STARTED.  
**HTTP 404**  
the job queue does not exist.  
**HTTP 503**  
an exception occurred during the start/restart attempt (server logs should be inspected to figure out what went wrong).

### Submit a job for launch
<a name="ba-submit-job-launch"></a>
+ Supported method: POST

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/submit`
+ Argument: mandatory as request body, a JSON serialization of a `com.netfective.bluage.gapwalk.rt.jobqueue.SubmitJobMessage` object. For more information, see [Submit job and schedule job input](ba-endpoints-apx.md#submit-job).
+ Returns a JSON containing the original `SubmitJobMessage` and a log indicating if the job has been submitted or not.

### List all submitted jobs
<a name="ba-list-scheduled-jobs"></a>
+ Supported method: GET

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/list-jobs?status={status}&size={size}&page={page}&sort={sort}`
+ Arguments:
  + page: Page number to retrieve (default = 1)
  + size: Size of the page (default = 50, max = 300)
  + sort: The order of the Jobs. (default = “executionId”). “executionId” is currently the only supported value
  + status: (optional) If present, it will filter on the status.
+ Returns a list of all scheduled jobs, as a JSON string. For a sample response, see [List of scheduled jobs response](ba-endpoints-apx.md#list-scheduled-jobs).

### Release all jobs that are "on hold"
<a name="ba-release-held-jobs"></a>
+ Supported method: POST

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/release-all`
+ Returns a message indicating the outcome for the release attempt operation. Two possible cases here:
  + HTTP 200 and a message "All job released with success\$1" if all jobs were successfully released.
  + HTTP 503 and a message "Jobs not released. An unknown error occurred. See log for more details" if something went wrong with the release attempt.

### Release all jobs that are "on hold" for a given job name
<a name="ba-release-held-jobs-name"></a>

For a given job name, multiple jobs can be submitted, with different job numbers (the unicity of a job run is granted by a couple <job name, job number>). The endpoint will attempt to release all job submissions with the given job name, which are "on hold".
+ Supported method: POST

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/release/{name}`
+ Arguments: the job name to look for, as a string. Mandatory.
+ Returns a message indicating the outcome for the release attempt operation. Two possible cases here:
  + HTTP 200 and a message "Jobs in group <name> (<number of released jobs>) released with success\$1" jobs were successfully released.
  + HTTP 503 and a message "Jobs in group <name> not released. An unknown error occured. See log for more details" if something went wrong with the release attempt.

### Release a given job for a job number
<a name="ba-release-job-number"></a>

The endpoint will attempt to release the unique job submission which is "on hold", for the given couple <job name, job number>.
+ Supported method: POST

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/release/{name}/{number}`
+ Arguments:  
**name**  
the job name to look for, as a string. Mandatory.  
**number**  
the job number to look for, as an integer. Mandatory.  
**returns**  
 a message indicating the outcome for the release attempt operation. Two possible cases here:  
  + HTTP 200 and a message ""Job <name/number> released with success\$1" if the job was successfully released.
  + HTTP 503 and a message "Job <name/number>>not released. An unknown error occured. See log for more details" if something went wrong with the release attempt.

### Submit a job on repeating schedule
<a name="ba-submit-job-on-repeating-schedule"></a>

Schedule a job that will be executed with a repeating schedule.
+ Supported method: POST

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/schedule`
+ Argument: the request body must contain a JSON serialization of a `com.netfective.bluage.gapwalk.rt.jobqueue.SubmitJobMessage` object. 

### List all submitted repeating jobs
<a name="ba-list-all-submitted-repeating-jobs"></a>
+ Supported method: GET

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN
+ Path: `/schedule/list?status={status}&size={size}&page={page}&sort={sort}`
+ Arguments:

  1. page: Page number to retrieve (default = 1)

  1. size: Size of the page (default = 50, max = 300)

  1. sort: The order of the Jobs. (default = “id”). “id” is the only supported value for now.

  1. status: (optional) If present, it will filter on the status. Possible values are the one mentioned in section 1.

  1. status: (optional) If present, it will filter on the status. Possible values are the one mentioned in section 1.

  1. Returns a list of all scheduled jobs, as a JSON string.

### Cancel the scheduling of a repeating job
<a name="ba-cancel-scheduling-of-repeating-job"></a>

Removes a job that was created on a repeating schedule. The job scheduling status is set to INACTIVE.
+ Supported method: POST

  Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN
+ Path: `/schedule/remove/{schedule_id}`
+ Argument: `schedule_id`, the identifier of the scheduled job to remove.

# Blusam application console REST endpoints
<a name="ba-endpoints-bac"></a>

In this section, you can learn about the Blusam application console, which is an API designed to simplify the management of modernized VSAM datasets. Endpoints for the Blusam web application use the root path `/bac`.

**Topics**
+ [Data sets related endpoints](#ba-endpoints-bac-datasets)
+ [Bulk data sets related endpoints](#ba-endpoints-bac-bulk)
+ [Records](#ba-endpoints-bac-records)
+ [Masks](#ba-endpoints-bac-masks)
+ [Other](#ba-endpoints-bac-other)
+ [BAC user-management endpoints](#ba-endpoints-bac-users)

## Data sets related endpoints
<a name="ba-endpoints-bac-datasets"></a>

Use the following endpoints to create or manage a specific data set.

**Topics**
+ [Create a data set](#ba-create-data-set)
+ [Upload a file](#ba-upload-file)
+ [Load a data set (POST)](#ba-load-data-set-post)
+ [Load a data set (GET)](#ba-load-data-set-get)
+ [Load a data set from an Amazon S3 bucket](#ba-load-data-set-s3)
+ [Export a data set to an Amazon S3 bucket](#ba-export-data-set-s3)
+ [Clear a data set](#ba-clear-data-set)
+ [Delete a data set](#ba-delete-data-set)
+ [Count data set records](#ba-count-data-set-records)

### Create a data set
<a name="ba-create-data-set"></a>

You can use this endpoint to create a data set definition.
+ Supported methods: POST
+ Requires authentication and the ROLE\$1ADMIN role.
+ Path: `/api/services/rest/bluesamservice/createDataSet`
+ Arguments:  
name  
(required, string): the name of the data set.   
type  
(required, string): the data set type. Possible values are: `ESDS`, `KSDS`, `RRDS`.   
recordSize  
(optional, string): Maximum size of each record of the data set.   
fixedLength  
(optional, boolean) : Indicates if the records length is fixed.   
compression  
(optional, boolean) : Indicates if the dataset is compressed.   
cacheEnable  
(optional, boolean) : Indicates if caching is enabled for the dataset.   
alternativeKeys  
(optional, list of keys):  
  + offset (required, number)
  + length (required, number)
  + name (required, number)
+ Returns a JSON file representing the newly created data set.

Sample request:

```
POST /api/services/rest/bluesamservice/createDataSet
{
  "name": "DATASET",
  "checked": false,
  "records": [],
  "primaryKey": {
    "name": "PK"
  },
  "alternativeKeys": [
    {
      "offset": 10,
      "length": 10,
      "name": "ALTK_0"
    }
  ],
  "type": "ESDS",
  "recordSize": 10,
  "compression": true,
  "cacheEnable": true
}
```

Sample response:

```
{
    "dataSet": {
      "name": "DATASET",
      "checked": false,
      "nbRecords": 0,
      "keyLength": -1,
      "recordSize": 10,
      "compression": false,
      "fixLength": true,
      "type": "ESDS",
      "cacheEnable": false,
      "cacheWarmup": false,
      "cacheEviction": "100ms",
      "creationDate": 1686744961234,
      "modificationDate": 1686744961234,
      "records": [],
      "primaryKey": {
        "name": "PK",
        "offset": null,
        "length": null,
        "columns": null,
        "unique": true
      },
      "alternativeKeys": [
        {
          "offset": 10,
          "length": 10,
          "name": "ALTK_0"
        }
      ],
      "readLimit": 0,
      "readEncoding": null,
      "initCharacter": null,
      "defaultCharacter": null,
      "blankCharacter": null,
      "strictZoned": null,
      "decimalSeparator": null,
      "currencySign": null,
      "pictureCurrencySign": null
    },
    "message": null,
    "result": true
  }
```

### Upload a file
<a name="ba-upload-file"></a>

You can use this endpoint to upload files to the server. The file is stored in a temporary folder that corresponds to each specific user. Use this endpoint every time you need to upload a file.
+ Supported methods: POST
+ Requires authentication and the ROLE\$1ADMIN role.
+ Path: `/api/services/rest/bluesamservice/upload`
+ Arguments:  
file  
(required, multipart/form-data): The file to upload.
+ Returns a boolean reflecting the status of the upload

### Load a data set (POST)
<a name="ba-load-data-set-post"></a>

After you use `createDataSet` to create the data set definition, you can load records that are associated with the uploaded file to a specific data set.
+ Supported methods: POST
+ Requires authentication and the ROLE\$1ADMIN role.
+ Path: `/api/services/rest/bluesamservice/loadDataSet`
+ Arguments:  
name  
(required, string): the name of the data set.
+ Returns the status of the request and the loaded data set.

### Load a data set (GET)
<a name="ba-load-data-set-get"></a>
+ Supported methods: GET
+ Requires authentication and the ROLE\$1ADMIN role.
+ Path: `/api/services/rest/bluesamservice/loadDataSet`
+ Arguments:  
listcatFileOrDatasetName  
(required, string): the name of the data set.  
datasetFile  
(required, string): the data set file name.
+ Returns the status of the request and the loaded data set.

### Load a data set from an Amazon S3 bucket
<a name="ba-load-data-set-s3"></a>

Loads a data set using a listcat file from an Amazon S3 bucket.
+ Supported methods: GET
+ Requires authentication and the ROLE\$1ADMIN role.
+ Path: `/api/services/rest/bluesamservice/loadDataSetFromS3`
+ Arguments:  
listcatFileS3Location  
(required, string): the Amazon S3 location of the listcat file.  
datasetFileS3Location  
(required, string): the Amazon S3 location of the data set file.  
region  
(required, string): the Amazon S3 AWS Region where the files are stored.
+ Returns the newly created data set

Sample request:

```
/BAC/api/services/rest/bluesamservice/loadDataSetFromS3?region=us-east-1&listcatFileS3Location=s3://bucket-name/listcat.json&datasetFileS3Location=s3://bucket-name/dataset.DAT
```

### Export a data set to an Amazon S3 bucket
<a name="ba-export-data-set-s3"></a>

Exports a data set to the specified Amazon S3 bucket.
+ Supported methods: GET
+ Requires authentication and the ROLE\$1ADMIN role.
+ Path: `/api/services/rest/bluesamservice/exportDataSetToS3`
+ Arguments:  
s3Location  
(required, string): the Amazon S3 location to export the data set to.  
datasetName   
(required, string): the name of the data set to export.  
region  
(required, string): the AWS Region of the Amazon S3 bucket.  
kmsKeyId  
(optional, string): the AWS KMS ID to be used for encryption of the exported data set to the Amazon S3 bucket.
+ Returns the exported data set

Sample request:

```
/BAC/api/services/rest/bluesamservice/exportDataSetToS3?region=eu-west-1&s3Location=s3://bucket-name/dump&datasetName=dataset
```

### Clear a data set
<a name="ba-clear-data-set"></a>

 Clears all records from a data set.
+ Supported methods: POST, GET
+ Requires authentication and the ROLE\$1ADMIN role.
+ Path: `/api/services/rest/bluesamservice/clearDataSet`
+ Arguments:   
name  
(required, string): the name of the data set to clear. When using the GET method, the parameter name is `datasetName`.
+ Returns the status of the request.

### Delete a data set
<a name="ba-delete-data-set"></a>

Deletes the data set definition and records.
+ Supported methods: POST
+ Requires authentication and the ROLE\$1ADMIN role.
+ Path: `/api/services/rest/bluesamservice/deleteDataSet`
+ Arguments:  
name  
(required, string): the name of the data set to delete.
+ Returns the status of the request and the deleted data set.

### Count data set records
<a name="ba-count-data-set-records"></a>

This endpoint returns the number of records associated with a data set.
+ Supported methods: POST
+ Requires authentication and the ROLE\$1USER role.
+ Path: `/api/services/rest/bluesamservice/countRecords`
+ Arguments:  
name  
(required, string): the name of the data set.
+ Returns: the number of records

## Bulk data sets related endpoints
<a name="ba-endpoints-bac-bulk"></a>

Use the following endpoints to create or manage multiple data sets at once.

**Topics**
+ [Export data sets (GET)](#ba-export-data-sets-get)
+ [Export data sets (POST)](#ba-export-data-sets-post)
+ [Create multiple data sets](#ba-create-multiple-data-sets)
+ [List all data sets](#ba-list-all-data-sets)
+ [Direct list all data sets](#ba-direct-list-all-data-sets)
+ [Direct list all data sets by page](#ba-direct-list-all-data-sets-by-page)
+ [Stream data set](#ba-stream-data-sets)
+ [Delete all data sets](#ba-delete-all-data-sets)
+ [Get data set definitions from listcat file](#ba-get-definitions-listcat)
+ [Get data set definitions from uploaded list cat file](#ba-get-definitions-uploaded-listcat)
+ [Get a data set](#ba-get-data-set)
+ [Load listcat from JSON file](#ba-load-listcat)

### Export data sets (GET)
<a name="ba-export-data-sets-get"></a>
+ Supported methods: GET
+ Requires authentication and the ROLE\$1ADMIN role.
+ Path: `/api/services/rest/bluesamservice/exportDataSet`
+ Arguments:  
datasetName  
(required, string): the name of the data set to export.   
datasetOutputFile  
(required, string): the path of the folder where you want to store the exported dataset on the server.  
rdw  
(required, boolean): whether you want the record descriptor word (RDW) to be part of the exported records. If the data set has fixed length records, the value of this parameter is ignored.
+ Returns the status of the request and the path to the file containing the exported data set (if any). If the dataset is null in the response, that means the system was not able to locate a data set with the given name.

### Export data sets (POST)
<a name="ba-export-data-sets-post"></a>
+ Supported methods: POST
+ Requires authentication and the ROLE\$1USER role.
+ Path: `/api/services/rest/bluesamservice/exportDataSet`
+ Arguments:  
dumpParameters  
(required, BACReadParameters): Bluesam read parameters.
+ Returns the status of the exported data set.

### Create multiple data sets
<a name="ba-create-multiple-data-sets"></a>
+ Supported methods: POST
+ Requires authentication and the ROLE\$1ADMIN role.
+ Path: `/api/services/rest/bluesamservice/createAllDataSets`
+ Arguments:
  + List of data sets  
name  
(required, string): the name of the data set.   
type  
(required, string): the data set type. Possible values are: `ESDS`, `KSDS`, `RRDS`.   
recordSize  
(optional, string) : Maximum size of each record of the data set.  
fixedLength  
(optional, boolean) : Indicates if the records length is fixed.  
compression  
(optional, boolean) : Indicates if the dataset is compressed.   
cacheEnable  
(optional, boolean) : Indicates if caching is enabled for the dataset.
+ Returns: the status of the request and the newly created data set.

### List all data sets
<a name="ba-list-all-data-sets"></a>
+ Supported methods: GET
+ Requires authentication and the ROLE\$1USER role.
+ Path: `/api/services/rest/bluesamservice/listDataSet`
+ Arguments: None
+ Returns: the status of the request and the list of the data sets.

### Direct list all data sets
<a name="ba-direct-list-all-data-sets"></a>
+ Supported methods: GET
+ Requires authentication and the ROLE\$1USER role.
+ Path: `/api/services/rest/bluesamservice/directListDataSet`
+ Arguments: None
+ Returns: the status of the request and the list of the data sets.

### Direct list all data sets by page
<a name="ba-direct-list-all-data-sets-by-page"></a>
+ Supported methods: GET
+ Requires authentication and the ROLE\$1USER role.
+ Path: `/api/services/rest/bluesamservice/directListDataSetByPage`
+ Arguments:  
name  
(required, string): the name of the data set. Defaults to `%` (all data sets) if not specified.  
page  
(required, int): the page number (minimum 0).  
pageSize  
(required, int): the page size (minimum 1, maximum 500).
+ Returns: the status of the request and the list of the data sets.

### Stream data set
<a name="ba-stream-data-sets"></a>
+ Supported methods: GET
+ Requires authentication and the ROLE\$1ADMIN role.
+ Path: `/api/services/rest/bluesamservice/streamDataset`
+ Arguments:  
datasetName  
(required, string): the name of the data set.
+ Returns: A stream of the requested data sets.

### Delete all data sets
<a name="ba-delete-all-data-sets"></a>
+ Supported methods: POST
+ Requires authentication and the ROLE\$1ADMIN role.
+ Path: `/api/services/rest/bluesamservice/removeAll`
+ Arguments: None
+ Returns: a boolean that represents the status of the request.

### Get data set definitions from listcat file
<a name="ba-get-definitions-listcat"></a>
+ Supported methods: POST
+ Requires authentication and the ROLE\$1ADMIN role.
+ Path: `/api/services/rest/bluesamservice/getDataSetsDefinitionFromListcat`
+ Arguments:   
paramFilePath  
(required, string): The path to the listcat file.
+ Returns: a list of data sets

### Get data set definitions from uploaded list cat file
<a name="ba-get-definitions-uploaded-listcat"></a>
+ Supported methods: POST
+ Requires authentication and the ROLE\$1ADMIN role.
+ Path: `/api/services/rest/bluesamservice/getDataSetsDefinitionFromUploadedListcat`
+ Arguments: None
+ Returns: a list of data sets

### Get a data set
<a name="ba-get-data-set"></a>
+ Supported methods: GET
+ Requires authentication and the ROLE\$1USER role.
+ Path: `/api/services/rest/bluesamservice/getDataSet`
+ Arguments:  
name  
(required, string): the name of the data set.
+ Returns the requested data set.

### Load listcat from JSON file
<a name="ba-load-listcat"></a>
+ Supported methods: GET
+ Requires authentication and the ROLE\$1ADMIN role.
+ Path: `/api/services/rest/bluesamservice/loadListcatFromJsonFile`
+ Arguments:   
filePath  
(required, string): The path to the listcat file.
+ Returns: a list of data sets

## Records
<a name="ba-endpoints-bac-records"></a>

Use the following endpoints to create or manage records within a data set.

**Topics**
+ [Create a record](#ba-create-record)
+ [Read a data set](#ba-read-data-set)
+ [Delete a record](#ba-delete-record)
+ [Update a record](#ba-update-record)
+ [Save a record](#ba-save-record)
+ [Validate a record](#ba-validate-record)
+ [Get a record tree](#ba-get-record-tree)

### Create a record
<a name="ba-create-record"></a>

You can use this endpoint to create a new record.
+ Supported methods: POST
+ Requires authentication and the ROLE\$1USER role.
+ Path: `/api/services/rest/crud/createRecord`
+ Arguments:  
dataset  
(required, DataSet): the data set object  
mask  
(required, mask): the mask object.
+ Returns the status of the request and the created record.

### Read a data set
<a name="ba-read-data-set"></a>

You can use this endpoint to read a data set.
+ Supported methods: POST
+ Requires authentication and the ROLE\$1USER role.
+ Path: `/api/services/rest/crud/readDataSet`
+ Arguments:  
dataset  
(required, DataSet): the data set object.
+ Returns the status of the request and the data set with the records.

### Delete a record
<a name="ba-delete-record"></a>

You can use this endpoint to delete a record from a data set.
+ Supported methods: POST
+ Requires authentication and the ROLE\$1USER role.
+ Path: `/api/services/rest/crud/deleteRecord`
+ Arguments:  
dataset  
(required, DataSet): the data set object  
record  
(required, Record): the record to delete
+ Returns the status of the deletion.

### Update a record
<a name="ba-update-record"></a>

You can use this endpoint to update a record associated with a data set.
+ Supported methods: POST
+ Requires authentication and the ROLE\$1USER role.
+ Path: `/api/services/rest/crud/updateRecord`
+ Arguments:  
dataset  
(required, DataSet): the data set object  
record  
(required, Record): the record to update  
mask  
(optional, Mask): the mask object to apply during the update.
+ Returns the status of the request and the data set with the records.

### Save a record
<a name="ba-save-record"></a>

You can use this endpoint to save a record to a data set and using a mask.
+ Supported methods: POST
+ Requires authentication and the ROLE\$1USER role.
+ Path: `/api/services/rest/crud/saveRecord`
+ Arguments:  
dataset  
(required, DataSet): the data set object  
record  
(required, Record): the record to save  
mask  
(optional, Mask): the mask object to apply during the save.
+ Returns the status of the request and the data set with the records.

### Validate a record
<a name="ba-validate-record"></a>

Use this endpoint to validate a record.
+ Supported methods: POST
+ Requires authentication and the ROLE\$1USER role.
+ Path: `/api/services/rest/crud/validateRecord`
+ Arguments:  
dataset  
(required, DataSet): the data set object  
record  
(optional, Record): the record to validate.  
mask  
(optional, Mask): the mask object to apply during validation.
+ Returns the status of the request and the data set with the records.

### Get a record tree
<a name="ba-get-record-tree"></a>

Use this endpoint to get the hierarchical tree of a record.
+ Supported methods: POST
+ Requires authentication and the ROLE\$1USER role.
+ Path: `/api/services/rest/crud/getRecordTree`
+ Arguments:  
dataset  
(required, DataSet): the data set object  
record  
(required, Record): the record to fetch  
mask  
(optional, Mask): the mask object.
+ Returns the status of the request and the hierarchical tree of the requested record.

## Masks
<a name="ba-endpoints-bac-masks"></a>

Use the following endpoints to load or apply masks to a data set.

**Topics**
+ [Load masks](#ba-load-mask)
+ [Apply mask](#ba-apply-mask)
+ [Apply mask filter](#ba-apply-mask-filter)

### Load masks
<a name="ba-load-mask"></a>

You can use this endpoint to retrieve all the masks that are associated with a specific data set.
+ Supported methods: POST
+ Requires authentication and the ROLE\$1USER role.
+ Path: `/api/services/rest/crud/loadMasks`
+ Path variables:  
recordSize: .../loadMasks/\$1recordSize\$1  
(optional, numeric): the record size, filter loaded masks that match this record size
+ Arguments:  
dataset  
(required, DataSet): the data set object
+ Returns the status of the request and the list of the masks.

### Apply mask
<a name="ba-apply-mask"></a>

You can use this endpoint to apply a mask to a specific data set.
+ Supported methods: POST
+ Requires authentication and the ROLE\$1USER role.
+ Path: `/api/services/rest/crud/applyMask`
+ Arguments:  
dataset  
(required, DataSet): the data set object  
mask  
(required, Mask): the data set object
+ Returns the status of the request and the data set with the applied mask.

### Apply mask filter
<a name="ba-apply-mask-filter"></a>

You can use this endpoint to apply a mask and a filter to a specific data set.
+ Supported methods: POST
+ Requires authentication and the ROLE\$1USER role.
+ Path: `/api/services/rest/crud/applyMaskFilter`
+ Arguments:  
dataset  
(required, DataSet): the data set object  
mask  
(required, Mask): the mask object  
filter  
(required, Filter): the filter object to apply.
+ Returns the status of the request and the data set with the applied mask and filter.

## Other
<a name="ba-endpoints-bac-other"></a>

Use the following endpoints to manage cache for a data set or check data set characteristics

**Topics**
+ [Check warm up cache](#ba-check-warm-up-cache)
+ [Check cache enabled](#ba-check-cache-enabled)
+ [Enable cache](#ba-enable-cache)
+ [Check allocated RAM cache](#ba-check-allocated-ram-cache)
+ [Check persistence](#ba-check-persistence)
+ [Check supported data set types](#ba-check-supported-data-set-types)
+ [Check server health](#ba-check-server-health)
+ [Check PostgreSQL multi-schema configuration](#ba-check-postgres-multi-schema)

### Check warm up cache
<a name="ba-check-warm-up-cache"></a>

Checks if the warmup cache is enabled for a specific data set.
+ Supported methods: POST
+ Requires authentication and the ROLE\$1ADMIN role.
+ Path: `/api/services/rest/bluesamservice/warmupCache`
+ Arguments:  
name  
(required, string): the name of the data set. 
+ Returns: true if the warm up cache is enabled and false otherwise.

### Check cache enabled
<a name="ba-check-cache-enabled"></a>

Checks if the cache is enabled for a specific data set.
+ Supported methods: GET
+ Requires authentication and the ROLE\$1USER role.
+ Path: `/api/services/rest/bluesamservice/isEnableCache`
+ Arguments: None
+ Returns true if the caching is enabled.

### Enable cache
<a name="ba-enable-cache"></a>
+ Supported methods: POST
+ Requires authentication and the ROLE\$1ADMIN and ROLE\$1SUPER\$1ADMIN roles.
+ Path: `/api/services/rest/bluesamservice/enableDisableCache/{enable}`
+ Arguments:   
enable  
(required, boolean): if set to true, it will enable caching.  
dataset  
(required, DataSet): the data set object.
+ Returns None

### Check allocated RAM cache
<a name="ba-check-allocated-ram-cache"></a>

You can use this endpoint to retrieve the allocated RAM cache memory.
+ Supported methods: GET
+ Requires authentication and the ROLE\$1USER role.
+ Path: `/api/services/rest/bluesamservice/allocatedRamCache`
+ Arguments: None
+ Returns: the size of the memory as a string

### Check persistence
<a name="ba-check-persistence"></a>
+ Supported methods: GET
+ Requires authentication and the ROLE\$1USER role.
+ Path: `/api/services/rest/bluesamservice/persistence`
+ Arguments: None
+ Returns: the persistence used as a string

### Check supported data set types
<a name="ba-check-supported-data-set-types"></a>
+ Supported methods: GET
+ Path: `/api/services/rest/bluesamservice/getDataSetTypes`
+ Requires authentication and the ROLE\$1USER role.
+ Arguments: None
+ Returns: the list of supported data set types as a list of strings.

### Check server health
<a name="ba-check-server-health"></a>
+ Supported methods: GET
+ Path: `/api/services/rest/bluesamserver/serverIsUp`
+ Arguments: None
+ Returns: None. HTTP response status code 200 indicates that the server is up and running.

### Check PostgreSQL multi-schema configuration
<a name="ba-check-postgres-multi-schema"></a>

Checks whether the PostgreSQL multi-schema configuration is enabled.
+ Supported methods: GET
+ Requires authentication and the ROLE\$1USER role.
+ Path: `/api/services/rest/bluesamservice/isPostgresMultiSchema`
+ Arguments: None
+ Returns: true if the PostgreSQL multi-schema configuration is enabled and false otherwise.

## BAC user-management endpoints
<a name="ba-endpoints-bac-users"></a>

Use the following endpoints to manage user interactions.

**Topics**
+ [Log a user in](#ba-log-user-in)
+ [Verify whether at least one user exists in the system](#ba-verify-at-least-one-user-exists)
+ [Record a new user](#ba-record-new-user)
+ [Get user info](#ba-user-info)
+ [List users](#ba-list-users)
+ [Delete a user](#ba-delete-user)
+ [Log the current user out](#ba-log-user-out)

### Log a user in
<a name="ba-log-user-in"></a>
+ Supported method: POST
+ Path: `/api/services/security/servicelogin/login`
+ Arguments: None
+ Returns the JSON serialization of a `com.netfective.bluage.bac.entities.SignOn` object, representing the user whose credentials are provided in the current request. The password is hidden from the view in the returned object. The roles given to the used are being listed.

Sample response:

```
{
     "login": "some-admin",
     "password": null,
     "roles": [
       {
         "id": 0,
         "roleName": "ROLE_ADMIN"
       }
     ]
   }
```

### Verify whether at least one user exists in the system
<a name="ba-verify-at-least-one-user-exists"></a>
+ Supported method: GET
+ Path: `/api/services/security/servicelogin/hasAccount`
+ Arguments: None
+ Returns the boolean value `true` if at least one user other than the default super admin user has been created. Returns `false` otherwise.

### Record a new user
<a name="ba-record-new-user"></a>
+ Supported method: POST
+ Requires authentication and the ROLE\$1ADMIN role.
+ Path: `/api/services/security/servicelogin/recorduser`
+ Arguments: the JSON serialization of a `com.netfective.bluage.bac.entities.SignOn` object that represents the user to be added to the storage. The roles for the user must be defined, otherwise the user might not be able to use the BAC facility and endpoints.
+ Returns the boolean value `true` if the user was successfully created. Returns `false` otherwise.
+ Sample request JSON:

  ```
   {
       "login": "simpleuser",
       "password": "simplepassword",
       "roles": [
         {
           "id": 2,
           "roleName": "ROLE_USER"
         }
       ]
     }
  ```

  The following are the two valid values for `roleName`: 
  + `ROLE_ADMIN`: can manage Blusam resources and users.
  + `ROLE_USER`: can manage Blusam resources but not users.

### Get user info
<a name="ba-user-info"></a>
+ Supported method: GET
+ Path: `/api/services/security/servicelogin/userInfo`
+ Arguments: None
+ Returns the username and role of the currently connected user

### List users
<a name="ba-list-users"></a>
+ Supported method: GET
+ Requires authentication and the ROLE\$1ADMIN role.
+ Path: `/api/services/security/servicelogin/listusers`
+ Arguments: None
+ Returns a list of `com.netfective.bluage.bac.entities.SignOn`, serialized as JSON.

### Delete a user
<a name="ba-delete-user"></a>

**Important**  
This action cannot be undone. The deleted user won't be able to connect to the BAC application again.
+ Supported method: POST
+ Requires authentication and the ROLE\$1ADMIN role.
+ Path: `/api/services/security/servicelogin/deleteuser`
+ Arguments: the JSON serialization of a `com.netfective.bluage.bac.entities.SignOn` object that represents the user to be removed from the storage.
+ Returns the boolean value `true` if the user was successfully removed.

### Log the current user out
<a name="ba-log-user-out"></a>
+ Supported method: GET
+ Path: `/api/services/security/servicelogout/logout`
+ Arguments: None
+ Returns the JSON message `{"success":true}` if the current user was successfully logged out. The related HTTP session will be invalidated.

# Manage JICS application console in AWS Transform for mainframe
<a name="ba-endpoints-jac"></a>

The JICS component is the AWS Transform for mainframe support for modernization of the legacy CICS resources. The JICS application console web application is dedicated to administrate JICS resources. The following endpoints allow to perform the administration tasks without having to interact with the JAC user interface. Whenever an endpoint requires authentication, the request will have to include authentication details (username/password typically, as required by Basic Authentication). Endpoints for the JICS application console web application use the root path `/jac/`.

**Topics**
+ [JICS resources management](#ba-endpoints-jac-resources)
+ [Other](#ba-endpoints-jac-other)
+ [JAC users management endpoints](#ba-endpoints-jac-users)

## JICS resources management
<a name="ba-endpoints-jac-resources"></a>

All following endpoints are related to JICS resources management, allowing JICS administrators to deal with resources on daily basis.

**Topics**
+ [List JICS LISTS and GROUPS](#list-jics-lists-groups)
+ [Retrieve JICS resources](#retrieve-jics-resources)
+ [List JICS GROUPS](#list-jics-groups)
+ [List JICS GROUPS for a given LIST](#list-jics-groups-given-list)
+ [LIST JICS resources for a given GROUP](#list-jics-resources-given-group)
+ [LIST JICS resources for a given GROUP (alternative using a name)](#list-jics-resources-given-group-alt)
+ [Editing the owned GROUPS of several LISTS](#edit-owned-groups-lists)
+ [Delete a LIST](#delete-list)
+ [Delete a GROUP](#delete-group)
+ [Delete a TRANSACTION](#delete-transaction)
+ [Delete a PROGRAM](#delete-program)
+ [Delete a FILE](#delete-file)
+ [Delete a TDQUEUE](#delete-tdqueue)
+ [Delete a TSMODEL](#delete-tsmodel)
+ [Delete elements](#delete-elements)
+ [Create a LIST](#create-list)
+ [Create a GROUP](#create-group)
+ [Common RESOURCES creation considerations](#common-create-considerations)
+ [Create a TRANSACTION](#create-transaction)
+ [Create a PROGRAM](#create-program)
+ [Create a FILE](#create-file)
+ [Create a TDQUEUE](#create-tdqueue)
+ [Create a TSMODEL](#create-tsmodel)
+ [Create elements](#create-elements)
+ [Update a LIST](#update-list)
+ [Update a GROUP](#update-group)
+ [Common RESOURCES update considerations](#common-update-considerations)
+ [Update a TRANSACTION](#update-transaction)
+ [Update a PROGRAM](#update-program)
+ [Update a FILE](#update-file)
+ [Update a TDQUEUE](#update-tdqueue)
+ [Update a TSMODEL](#update-tsmodel)
+ [Update elements](#update-elements)
+ [Upsert elements](#upsert-elements)
+ [Retrieve elements](#retrieve-elements)
+ [JICS CRUD operation](#jics-crud-operation)

### List JICS LISTS and GROUPS
<a name="list-jics-lists-groups"></a>

The LIST and GROUPS are the main owning container resources within the JICS component. All JICS resources must belong to a GROUP. Groups can belong to LISTS, but this is not mandatory. LISTS might even not exist on a given JICS environment, but most of the time, LISTS are there to give an extra layer of organization for resources. For more information about the CICS resources organization, see [CICS resources](https://www.ibm.com/docs/en/cics-ts/6.1?topic=fundamentals-how-it-works-cics-resources).
+ Supported method: GET
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/listJicsListsAndGroups`
+ Arguments: None
+ Returns: a list of serialized JicsContainer objects, both LISTS and GROUPS, as JSON.

Sample response:

```
[
    {
      "name": "Resources",
      "children": [
        {
          "jacType": "JACList",
          "name": "MURACHS",
          "isActive": true,
          "children": [
            {
              "jacType": "JACGroup",
              "name": "MURACHS",
              "isActive": true,
              "children": []
            }
          ]
        },
        {
          "jacType": "JACGroup",
          "name": "TEST",
          "isActive": true,
          "children": []
        }
      ],
      "isExpanded": true
    }
  ]
```

### Retrieve JICS resources
<a name="retrieve-jics-resources"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/retrieveJicsResources`
+ Arguments: A JSON payload that represents the JICS resources that you want to retrieve. This is the JSON serialization of a `com.netfective.bluage.jac.entities.request.RetrieveOperationRequest` object.
+ Returns: A list of serialized JicsResource objects. The objects are returned in no particular order and are of different types, like PROGRAM, TRANSACTION, FILE, and so on.

### List JICS GROUPS
<a name="list-jics-groups"></a>
+ Supported method: GET
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/listJicsGroups`
+ Arguments: None
+ Returns a list of serialized JicsContainer objects (GROUPS) as JSON. The GROUPS are returned without their owning LIST information.

Sample response:

```
[
    {
      "jacType": "JACGroup",
      "name": "MURACHS",
      "isActive": true,
      "children": []
    },
    {
      "jacType": "JACGroup",
      "name": "TEST",
      "isActive": true,
      "children": []
    }
  ]
```

### List JICS GROUPS for a given LIST
<a name="list-jics-groups-given-list"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/listGroupsForList`
+ Arguments: a JSON payload, representing the JICS LIST whose GROUPS you're looking for. This is the JSON serialization of a `com.netfective.bluage.jac.entities.JACList` object.

  Sample request:

  ```
  {
      "jacType":"JACList",
      "name":"MURACHS",
      "isActive":true
    }
  ```
+ Returns a list of serialized JicsContainer objects (GROUPS) as JSON, that are attached to the given LIST. The GROUPS are returned without their owning LIST information.

  Sample response:

  ```
  [
      {
        "jacType": "JACGroup",
        "name": "MURACHS",
        "isActive": true,
        "children": []
      }
    ]
  ```

### LIST JICS resources for a given GROUP
<a name="list-jics-resources-given-group"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/listResourcesForGroup`
+ Arguments: a JSON payload, representing the JICS GROUP whose resources you're looking for. This is the JSON serialization of a `com.netfective.bluage.jac.entities.JACGroup` object. You do not need to specify all fields for the GROUP, but the name is mandatory.

  Sample request:

  ```
  {
      "jacType":"JACGroup",
      "name":"MURACHS",
      "isActive":true
    }
  ```
+ Returns a list of serialized JicsResource objects, owned by the given GROUP. The objects are returned in no particular order and are of different types, like PROGRAM, TRANSACTION, FILE, and so on.

### LIST JICS resources for a given GROUP (alternative using a name)
<a name="list-jics-resources-given-group-alt"></a>
+ Supported method: POST
+ Requires authentication
+ Path: `/api/services/rest/jicsservice/listResourcesForGroupName`
+ Arguments: the name of the GROUP owning the resources you're looking for.
+ Returns: a list of serialized JicsResource objects, owned by the given GROUP. The objects are being returned in no particular order and are of different types, like PROGRAM, TRANSACTION, FILE, and so on.

### Editing the owned GROUPS of several LISTS
<a name="edit-owned-groups-lists"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/editGroupsList`
+ Arguments: a JSON representation of a collection of LISTS with children GROUPS;

  Sample request:

  ```
  [      
    {
          "jacType": "JACList",
          "name": "MURACHS",
          "isActive": true,
          "children": [
            {
              "jacType": "JACGroup",
              "name": "MURACHS",
              "isActive": true,
              "children": []
            },
            {
              "jacType": "JACGroup",
              "name": "TEST",
              "isActive": true,
              "children": []
            }
          ]
    }
  ]
  ```

  Prior to this editing, only the group named "MURACHS" belonged to the LIST named "MURACHS". With this editing, you "add" the group named "TEST" to the LIST named "MURACHS".
+ Returns a boolean value. If the value is 'true', the LISTS modifications were successfully persisted to the underlying JICS storage.

### Delete a LIST
<a name="delete-list"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/deleteList`
+ Arguments: a JSON payload, representing the JICS LIST to delete. This is the JSON serialization of a `com.netfective.bluage.jac.entities.JACList` object.
+ Returns a boolean value. If the value is 'true', the LIST deletion was successfully operated on the underlying JICS storage.

### Delete a GROUP
<a name="delete-group"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/deleteGroup`
+ Arguments: a JSON payload, representing the JICS GROUP to delete. This is the JSON serialization of a `com.netfective.bluage.jac.entities.JACGroup` object.
+ Returns a boolean value. If the value is 'true', the GROUP deletion was successfully operated on the underlying JICS storage.

### Delete a TRANSACTION
<a name="delete-transaction"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/deleteTransaction`
+ Arguments: a JSON payload, representing the JICS Transaction to delete. This is the JSON serialization of a `com.netfective.bluage.jac.entities.JACTransaction` object.
+ Returns a boolean value. If the value is 'true', the TRANSACTION deletion was successfully operated on the underlying JICS storage.

### Delete a PROGRAM
<a name="delete-program"></a>
+ Supported method: POST
+ Requires authentication and one the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/deleteProgram`
+ Arguments: a JSON payload, representing the JICS Program to delete. This is the JSON serialization of a `com.netfective.bluage.jac.entities.JACProgram` object.
+ Returns a boolean value. If the value is 'true', the PROGRAM deletion was successfully operated on the underlying JICS storage.

### Delete a FILE
<a name="delete-file"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/deleteFile`
+ Arguments: a JSON payload, representing the JICS File to delete. This is the JSON serialization of a `com.netfective.bluage.jac.entities.JACFile` object.
+ Returns a boolean value. If the value is 'true', the FILE deletion was successfully operated on the underlying JICS storage.

### Delete a TDQUEUE
<a name="delete-tdqueue"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/deleteTDQueue`
+ Arguments: a JSON payload, representing the JICS TDQUEUE to delete. This is the JSON serialization of a `com.netfective.bluage.jac.entities.JACTDQueue` object.
+ Returns a boolean value. If the value is 'true', the TDQUEUE deletion was successfully operated on the underlying JICS storage.

### Delete a TSMODEL
<a name="delete-tsmodel"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/deleteTSModel`
+ Arguments: a JSON payload, representing the JICS TSMODEL to delete. This is the JSON serialization of a `com.netfective.bluage.jac.entities.JACTSModel` object.
+ Returns a boolean value. If the value is 'true', the TSMODEL deletion was successfully operated on the underlying JICS storage.

### Delete elements
<a name="delete-elements"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/deleteElements`
+ Arguments: A JSON payload that represents the JICS elements to delete.
+ Returns a boolean value where `true` indicates that the deletion was successfully operated in the underlying JICS storage.

### Create a LIST
<a name="create-list"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/createList`
+ Arguments: a JSON payload, representing the JICS LIST to create. This is the JSON serialization of a `com.netfective.bluage.jac.entities.JACList` object.
+ Returns a boolean value. If the value is 'true', the LIST was successfully created in the underlying JICS storage.

**Note**  
The LIST will always be created empty. Attaching GROUPS to the LIST will require another operation.

### Create a GROUP
<a name="create-group"></a>
+ Supported method: POST
+ Requires authentication and the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/createGroup`
+ Arguments: a JSON payload, representing the JICS GROUP to create. This is the JSON serialization of a `com.netfective.bluage.jac.entities.JACGroup` object.
+ Returns a boolean value. If the value is 'true', the GROUP has been properly created in the underlying JICS storage.

**Note**  
The GROUP will always be created empty. Attaching RESOURCES to the GROUP will require additional operations (creating resources will automatically attach them to a given GROUP.

### Common RESOURCES creation considerations
<a name="common-create-considerations"></a>

All the following endpoints are related to JICS RESOURCES creation and share some common constraints: in the request payload to be sent to the endpoint, the `groupName` field has to be valued.

GROUP ownership constraint:

No resource can be created without being attached to an existing group, and the endpoint uses the groupName to retrieve the group to which this resource will be attached. The `groupName` must point to the name of an existing GROUP. An error message with HTTP STATUS 400 will be sent if the `groupName` is not pointing at an existing group in the JICS underlying storage.

Unicity constraint within a GROUP:

A given resource with a given name must be unique within a given group. The check for unicity will be performed by each resource creation endpoint. If the given payload does not respect the unicity constraint, the endpoint will send a response with HTTP STATUS 400 (BAD REQUEST) -- see the sample response below.

Sample payload: you try to create the transaction 'ARIT' in the 'TEST' group, but a transaction with that name already exists in that group.

```
{
    "jacType":"JACTransaction",
    "name":"ARIT", 
    "groupName":"TEST", 
    "isActive":true
  }
```

You receive the following error response:

```
{
    "timestamp": 1686759054510,
    "status": 400,
    "error": "Bad Request",
    "path": "/jac/api/services/rest/jicsservice/createTransaction"
  }
```

Inspecting servers logs will confirm the origin of the issue:

```
2023-06-14 18:10:54 default         TRACE - o.s.w.m.HandlerMethod                    - Arguments: [java.lang.IllegalArgumentException: Transaction already present in the group, org.springframework.security.web.header.HeaderWriterFilter$HeaderWriterResponse@e34f6b8]
2023-06-14 18:10:54 default         ERROR - c.n.b.j.a.WebConfig                      - 400
java.lang.IllegalArgumentException: Transaction already present in the group
	at com.netfective.bluage.jac.server.services.rest.impl.JicsServiceImpl.createElement(JicsServiceImpl.java:1280)
```

### Create a TRANSACTION
<a name="create-transaction"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/createTransaction`
+ Arguments: a JSON payload, representing the JICS TRANSACTION to create. This is the JSON serialization of a `com.netfective.bluage.jac.entities.JACTransaction` object.
+ Returns a boolean value. If the value is 'true', the TRANSACTION was successfully created in the underlying JICS storage.

### Create a PROGRAM
<a name="create-program"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/createProgram`
+ Arguments: a JSON payload, representing the JICS PROGRAM to create. This is the JSON serialization of a `com.netfective.bluage.jac.entities.JACProgram` object.
+ Returns a boolean value. If the value is 'true', the PROGRAM was successfully created in the underlying JICS storage.

### Create a FILE
<a name="create-file"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/createFile`
+ Arguments: a JSON payload, representing the JICS FILE to create. This is the JSON serialization of a `com.netfective.bluage.jac.entities.JACFile` object.
+ Returns a boolean value. If the value is 'true', the FILE was successfully created in the underlying JICS storage.

### Create a TDQUEUE
<a name="create-tdqueue"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/createTDQueue`
+ Arguments: a JSON payload, representing the JICS TDQUEUE to create. This is the JSON serialization of a `com.netfective.bluage.jac.entities.JACTDQueue` object.
+ Returns a boolean value. If the value is 'true', the TDQUEUE was successfully created in the underlying JICS storage.

### Create a TSMODEL
<a name="create-tsmodel"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/createTSModel`
+ Arguments: a JSON payload, representing the JICS TSMODEL to create. This is the JSON serialization of a `com.netfective.bluage.jac.entities.JACTSModel` object.
+ Returns a boolean value where `true` indicates that the creation of elements was successfully operated in the underlying JICS storage.

### Create elements
<a name="create-elements"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/createElements`
+ Arguments: a JSON payload that represents the JICS elements to create.
+ Returns a boolean value. If the value is 'true', the elements were successfully created in the underlying JICS storage.

### Update a LIST
<a name="update-list"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/updateList`
+ Arguments: a JSON payload, representing the JICS LIST to update. This is the JSON serialization of a `com.netfective.bluage.jac.entities.JACList` object. There's no need to supply the children of the LIST; the LIST update mechanism won't take the children into account. 
+ Returns a boolean value. If the value is 'true', the LIST was successfully updated in the underlying JICS storage.

Updating the LIST 'isActive' flag will propagate to all owned elements of the LIST, that is, all GROUPS owned by the LIST and all RESOURCES owned by those GROUPS. This is a convenient way of deactivating a lot of resources with a single operation, over several GROUPS.

### Update a GROUP
<a name="update-group"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/updateGroup`
+ Arguments: a JSON payload, representing the JICS GROUP to update. This is the JSON serialization of a `com.netfective.bluage.jac.entities.JACGroup` object. There's no need to supply the children of the GROUP, the GROUP update mechanism won't take this into account. 
+ Returns a boolean value. If the value is 'true', the GROUP was successfully updated in the underlying JICS storage.

**Note**  
Updating the GROUP 'isActive' flag will propagate to all owned elements of the GROUP, that is, all RESOURCES owned by the GROUP. This is a convenient way of deactivating a lot of resources with a single operation within a given GROUP.

### Common RESOURCES update considerations
<a name="common-update-considerations"></a>

All following endpoints are about updating JICS RESOURCES. Using the `groupName` field, you can change the owning GROUP of any JICS RESOURCE, provided the field value points to an existing GROUP in the underlying JICS storage (otherwise, you will get a BAD REQUEST response (HTTP STATUS 400) from the endpoint).

### Update a TRANSACTION
<a name="update-transaction"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/updateTransaction`
+ Arguments: a JSON payload, representing the JICS TRANSACTION to update. This is the JSON serialization of a `com.netfective.bluage.jac.entities.JACTransaction` object.
+ Returns a boolean value. If the value is 'true', the TRANSACTION was successfully updated in the underlying JICS storage.

### Update a PROGRAM
<a name="update-program"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/updateProgram`
+ Arguments: a JSON payload, representing the JICS PROGRAM to update. This is the JSON serialization of a `com.netfective.bluage.jac.entities.JACProgram` object.
+ Returns a boolean value. If the value is 'true', the PROGRAM was successfully updated in the underlying JICS storage.

### Update a FILE
<a name="update-file"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/updateFile`
+ Arguments: a JSON payload, representing the JICS FILE to update. This is the JSON serialization of a `com.netfective.bluage.jac.entities.JACFile` object.
+ Returns a boolean value. If the value is 'true', the FILE was successfully updated in the underlying JICS storage.

### Update a TDQUEUE
<a name="update-tdqueue"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/updateTDQueue`
+ Arguments: a JSON payload, representing the JICS TDQUEUE to update. This is the JSON serialization of a `com.netfective.bluage.jac.entities.JACTDQueue` object.
+ Returns a boolean value. If the value is 'true', the TDQueue was successfully updated in the underlying JICS storage.

### Update a TSMODEL
<a name="update-tsmodel"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/updateTSModel`
+ Arguments: a JSON payload, representing the JICS TSMODEL to update. This is the JSON serialization of a `com.netfective.bluage.jac.entities.JACTSModel` object.
+ Returns a boolean value. If the value is 'true', the TSMODEL was successfully updated in the underlying JICS storage.

### Update elements
<a name="update-elements"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/updateElements`
+ Arguments: A JSON payload that represents the elements to update.
+ Returns a boolean value where `true` indicates that the elements update was successfully operated in the underlying JICS storage.

### Upsert elements
<a name="upsert-elements"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/upsertElements`
+ Arguments: A JSON payload that represents the elements to upsert.
+ Returns a boolean value where `true` indicates that the elements upsert was successfully operated in the underlying JICS storage.

### Retrieve elements
<a name="retrieve-elements"></a>
+ Supported method: GET
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/retrieveElements`
+ Arguments: None
+ Returns a list of all serialized JICS resources.

### JICS CRUD operation
<a name="jics-crud-operation"></a>
+ Supported method: POST
+ Requires authentication and one of the following roles: ROLE\$1ADMIN, ROLE\$1SUPER\$1ADMIN, ROLE\$1USER
+ Path: `/api/services/rest/jicsservice/jicsCrudOperation`
+ Arguments: a JSON payload that represents the JICS resources you're looking for. This is the JSON serialization of a `com.netfective.bluage.jac.entities.request.JicsCrudOperationRequest` object.
+ Returns a JSON payload that represents the response. This is the JSON serialization of a `com.netfective.bluage.jac.entities.request.JicsCrudOperationResponse` object.

## Other
<a name="ba-endpoints-jac-other"></a>

**Topics**
+ [JICS server health status](#jics-server-health)

### JICS server health status
<a name="jics-server-health"></a>
+ Supported method: GET
+ Path: `/api/services/rest/jicsserver/serverIsUp`
+ Arguments: None
+ Returns: None. An HTTP STATUS 200 response indicates that the server is up and running.

## JAC users management endpoints
<a name="ba-endpoints-jac-users"></a>

Use the following endpoints to manage user interactions.

**Topics**
+ [Logging a user](#log-user)
+ [Testing if at least an user exists in the system](#test-user-exist)
+ [Recording a new user](#record-new-user)
+ [User info](#user-info)
+ [Listing users](#list-users)
+ [Deleting a user](#delete-user)
+ [Logout the current user](#logout-user)

### Logging a user
<a name="log-user"></a>
+ Supported method: POST
+ Path: `/api/services/security/servicelogin/login`
+ Arguments: None
+ Returns the JSON serialization of a `com.netfective.bluage.jac.entities.SignOn` object, representing the user whose credentials are provided in the current request. The password is hidden from the view in the returned object. The roles given to the used are being listed.

Sample response:

```
{
    "login": "some-admin",
    "password": null,
    "roles": [
      {
        "id": 0,
        "roleName": "ROLE_ADMIN"
      }
    ]
  }
```

### Testing if at least an user exists in the system
<a name="test-user-exist"></a>
+ Supported method: GET
+ Path: `/api/services/security/servicelogin/hasAccount`
+ Arguments: None
+ Returns the boolean value `true` if at least one user other than the default super admin user has been created. Returns `false` otherwise.

### Recording a new user
<a name="record-new-user"></a>
+ Supported method: POST
+ Requires authentication and the ROLE\$1ADMIN role.
+ Path: `/api/services/security/servicelogin/recorduser`
+ Arguments: the JSON serialization of a `com.netfective.bluage.jac.entities.SignOn` object, representing the user to be added to the storage. The Roles for the user should be defined, otherwise the user might not be able to use the JAC facility and endpoints.
+ Returns the boolean value `true` if the user was successfully created. Returns `false` otherwise.

Sample request:

```
{
    "login": "simpleuser",
    "password": "simplepassword",
    "roles": [
      {
        "id": 2,
        "roleName": "ROLE_USER"
      }
    ]
  }
```

Only the following roles can be used when recording a new user:
+ ROLE\$1ADMIN : can manage JICS resources and users.
+ ROLE\$1USER : can manage JICS resources but not users.

### User info
<a name="user-info"></a>
+ Supported method: GET
+ Path: `/api/services/security/servicelogin/userInfo`
+ Arguments: None
+ Returns the username and roles of the currently connected user.

### Listing users
<a name="list-users"></a>
+ Supported method: GET
+ Requires authentication and the ROLE\$1ADMIN role.
+ Path: `/api/services/security/servicelogin/listusers`
+ Arguments: None
+ Returns a list of `com.netfective.bluage.jac.entities.SignOn`, serialized as JSON.

### Deleting a user
<a name="delete-user"></a>
+ Supported method: POST
+ Requires authentication and the ROLE\$1ADMIN role.
+ Path: `/api/services/security/servicelogin/deleteuser`
+ Arguments: the JSON serialization of a `com.netfective.bluage.jac.entities.SignOn` object that represents the user to be removed from the storage.
+ Returns the boolean value `true` if the user was successfully removed.

**Important**  
This action cannot be undone. The deleted user won't be able to connect to the JAC application again.

### Logout the current user
<a name="logout-user"></a>
+ Supported method: GET
+ Path: `/api/services/security/servicelogout/logout`
+ Arguments: None
+ Returns the JSON message `{"success":true}` if the current user was successfully logged out. The related HTTP session will be invalidated.

# Data structures for AWS Transform for mainframe user
<a name="ba-endpoints-apx"></a>

You can learn about various data structures for AWS Transform for mainframe engine in the following section.

**Topics**
+ [Job execution details message structure](#job-execution-details)
+ [Transaction launch outcome structure](#transaction-outcome)
+ [Transaction launch record outcome structure](#transaction-record-outcome)
+ [Possible status of a job on a queue](#jobs-status)
+ [Submit job and schedule job input](#submit-job)
+ [List of scheduled jobs response](#list-scheduled-jobs)
+ [List of repeating jobs response](#list-on-hold-jobs)

## Job execution details message structure
<a name="job-execution-details"></a>

Each job execution details will have the following fields:

scriptId  
the identifier of the called script.

caller  
I.P. address of the caller.

identifier  
unique job execution identifier.

startTime  
date and time at which the job execution started.

endTime  
date and time at which the job execution ended.

status  
a status for the job execution. One possible value amongst:  
+ `DONE`: job execution ended normally.
+ `TRIGGERED`: job execution triggered but not launched yet.
+ `RUNNING`: job execution is running.
+ `KILLED`: job execution has been killed.
+ `FAILED`: job execution has failed.

executionResult  
a message to sum up the outcome of the job execution. This message can either be a simple message if the job execution is not finished yet or a JSON structure with the following fields:  
+ exitCode: numeric exit code; negative values indicate failure situations.
+ program: latest program launched by the job.
+ status: one possible value amongst:
  + `Error`: when exitCode = -1; this corresponds to an (technical) error occurring during job execution.
  + `Failed`: when exitcode = -2; This corresponds to a failure occurring during a service program execution (like an ABEND situation).
  + `Succeeded`: when exitCode >= 0;
+ stepName: name of the latest step executed in the job.

executionMode  
either SYNCHRONOUS or ASYNCHRONOUS, depending on the way the job has been launched.

Sample output:

```
{
    "scriptId": "INTCALC",
    "caller": "127.0.0.1",
    "identifier": "97d410be-efa7-4bd3-b7b9-d080e5769771",
    "startTime": "06-09-2023 11:42:41",
    "endTime": "06-09-2023 11:42:42",
    "status": "DONE",
    "executionResult": "{ \"exitCode\": -1, \"stepName\": \"STEP15\", \"program\": \"CBACT04C\", \"status\": \"Error\" }",
    "executionMode": "ASYNCHRONOUS"
  }
```

## Transaction launch outcome structure
<a name="transaction-outcome"></a>

 The structure might contain the following fields:

outCome  
a string representing the transaction execution outcome. Possible values are:  
+ `Success`: transaction execution went to the end properly.
+ `Failure`: transaction execution failed to end properly, some problem(s) were encountered.

commarea  
a string representing the COMMAREA final value, as a byte64 encoded byte array. Might be an empty string.

containerRecord  
(Optional) a string representing the CONTAINER's record content as a byte64 encoded byte array.

serverDescription  
May contain information about the server which served the request (for debugging purpose). Might be an empty string.

abendCode  
(Optional) if the program referenced by the launched transaction abended, the abend code value will be returned as as string in this field.

Sample responses:

Success

```
{
    "outCome": "Success",
    "commarea": "",
    "serverDescription": ""
  }
```

Failure

```
{
    "outCome": "Failure",
    "commarea": "",
    "serverDescription": "",
    "abendCode": "AEIA"
  }
```

## Transaction launch record outcome structure
<a name="transaction-record-outcome"></a>

The structure might contain the following fields:

recordContent  
a string representing the COMMAREA's record content as a byte64 encoded byte array.

containerRecord  
a string representing the CONTAINER's record content as a byte64 encoded byte array.

serverDescription  
May contain information about the server which served the request (for debugging purpose). Might be an empty string.

Sample responses:

Success

```
{
    "recordContent": "",
    "serverDescription": ""
}
```

## Possible status of a job on a queue
<a name="jobs-status"></a>

On a queue, jobs can have the following status:

ACTIVE  
The job is currently being run on the queue.

EXECUTION\$1WAIT  
The job is waiting for a thread to be available.

SCHEDULED  
Jobs is scheduled for execution at a specific date and time.

HOLD  
Job is waiting to be released before being run.

COMPLETED  
Job has been executed successfully.

FAILED  
Job execution has failed.

UNKNOWN  
Status is unknown.

## Submit job and schedule job input
<a name="submit-job"></a>

The submit job and schedule job input is the JSON serialization of a `com.netfective.bluage.gapwalk.rt.jobqueue.SubmitJobMessage` object. The sample input below exhibits all the fields for such a bean.

Sample input for submit job:

```
{
    "messageQueueName":null,
    "scheduleDate":null,
    "scheduleTime":null,
    "programName":"PTA0044",
    "programParams":
     {"wmind":"B"},
    "localDataAreaValue":"",
    "userName":"USER1",
    "jobName":"PTA0044",
    "jobNumber":9,
    "jobPriority":5,
    "executionDate":"20181231",
    "jobQueue":"queue1",
    "jobOnHold":false
}
```

Sample input for schedule job:

```
{
     "scheduleCron": "*/2 * * * * ?",
     "programName":"LOGPGM",
     "programParams": {
         "cl_sbmjob_param_json": "[\"./output/schedule-job-log.txt\", \"Every 2 seconds!\"]"
     },
     "localDataAreaValue":"",
     "userName":"PVO",
     "jobName":"LOGGERJOB",
     "jobPriority":5,
     "jobQueue":"queue1",
     "scheduleMisfirePolicy": 4,
     "startTime": "2003/05/04 07:00:00.000 GMT-06:00",
     "endTime": "2003/05/04 07:00:07.000 GMT-06:00"
 }
```

jobNumber  
if the job number is 0, the job number will be automatically generated using the next number in the job number sequence. That value should be set to 0 (except for testing purpose).

jobPriority  
Default job priority in AS400 is 5. Valid range is 0-9, 0 being the highest priority.

jobOnHold  
If a job is submitted on hold, it won’t be executed right away but only when somebody “releases” it. A job can be released using the REST API (/release or /release-all).

scheduleDate and scheduleTime  
If these values are not null, the job will be executed at the specified date and time. 

Date  
Can be provided with format MMddyy or ddMMyyyy (size of the input will determine what format is used)

Time  
Can be provided with format HHmm or HHmmss (size of the input will determine what format is used)

programParams  
Will be passed to the program as a map.

scheduleMisfirePolicy  
Defines the strategy used when a trigger is misfired. The following are the possible values:  

1. Release the first misfire and discard the other misfires.

1. Submit a job on hold for the first misfire and discard the other misfires.

1. Discard the misfire.

1. Release all misfires. The job queue will run all jobs.

## List of scheduled jobs response
<a name="list-scheduled-jobs"></a>

 This is the structure of the list-jobs job queue endpoint. The submit job message that was used to submit that job is part of the response. This can be used for tracking or testing / resubmitting purpose. When a job is completed, the start date and end date will also be populated.

```
[
  {
    "jobName": "PTA0044",
    "userName": "USER1",
    "jobNumber": 9,
    "jobPriority": 5,
    "status": "HOLD",
    "jobDelay": 0,
    "startDate": null,
    "endDate": null,
    "jobQueue": "queue1",
    "message": {
      "messageQueueName": null,
      "scheduleDate": null,
      "scheduleTime": null,
      "programName": "PTA0044",
      "programParams": {"wmind": "B"},
      "localDataAreaValue": "",
      "userName": "USER1",
      "jobName": "PTA0044",
      "jobNumber": 9,
      "jobPriority": 5,
      "executionDate": "20181231",
      "jobQueue": "queue1",
      "jobOnHold": true,
      "scheduleCron": null,
      "save": false,
      "scheduleMisfirePolicy": 4,
      "omitdates": null
    },
    "executionId": 1,
    "jobScheduledId": 0,
    "jobScheduledAt": null
  },
  {
    "jobName": "PTA0044",
    "userName": "USER1",
    "jobNumber": 9,
    "jobPriority": 5,
    "status": "COMPLETED",
    "jobDelay": 0,
    "startDate": "2022-10-13T22:48:34.025+00:00",
    "endDate": "2022-10-13T22:52:54.475+00:00",
    "jobQueue": "queue1",
    "message": {
      "messageQueueName": null,
      "scheduleDate": null,
      "scheduleTime": null,
      "programName": "PTA0044",
      "programParams": {"wmind": "B"},
      "localDataAreaValue": "",
      "userName": "USER1",
      "jobName": "PTA0044",
      "jobNumber": 9,
      "jobPriority": 5,
      "executionDate": "20181231",
      "jobQueue": "queue1",
      "jobOnHold": true,
      "scheduleCron": "*/20 * * * * ?",
      "save": false,
      "scheduleMisfirePolicy": 4,
      "omitdates": null
    },
    "executionId": 2,
    "jobScheduledId": 0,
    "jobScheduledAt": null
  }
]
```

## List of repeating jobs response
<a name="list-on-hold-jobs"></a>

This is the structure of the /schedule/list job queue endpoint.

```
[
  {
    "id": 1,
    "status": "ACTIVE",
    "jobNumber": 1,
    "userName": "PVO",
    "msg": {
      "messageQueueName": null,
      "scheduleDate": null,
      "scheduleTime": null,
      "startTime": "2024/03/07 21:12:00.000 UTC",
      "endTime": "2024/03/07 21:13:59.000 UTC",
      "programName": "LOGPGM",
      "programParams": {"cl_sbmjob_param_json": "[\"./output/schedule-job-log.txt\", \"Every 20 seconds!\"]"},
      "localDataAreaValue": "",
      "userName": "PVO",
      "jobName": "LOGGERJOB",
      "jobNumber": 1,
      "jobScheduleId": 1,
      "jobPriority": 5,
      "executionDate": null,
      "jobQueue": "queue1",
      "jobOnHold": false,
      "scheduleCron": "*/20 * * * * ?",
      "save": false,
      "scheduleMisfirePolicy": 4,
      "omitdates": null
    },
    "lastUpdatedAt": "2024-03-07T21:11:13.282+00:00",
    "lastUpdatedBy": ""
  }
]
```