HaloENGINE API

Secude’s HaloENGINE API architecture aims to streamline underlying MPIP functionalities such as file protection and audit log export. The HaloENGINE API enables MPIP capabilities by seamlessly integrating with existing business applications.

HaloENGINE API

What can be expected when using the API?

It streamlines web-based application interaction via HTTP methods.
The end consumer can protect files with their own rule engine or business logic.
This will extend to any existing or customized data portal within the organization that must be scrutinized and protected against data leaks.

The usage of this information, as well as the implementation of any of these APIs, is the responsibility of the customer and is dependent on their abilities to evaluate and incorporate them into their place of business.

About this Manual

This document demonstrates how to successfully call the HaloENGINE API from your application and use it for your business needs. It assumes you are familiar with REST API calls. It provides a clear and comprehensive background to the REST SDK, including endpoints, parameters, response types, and any other information that developers should be aware of. It also explains how the resources work and provides examples that should help you get started.

Please be aware that the examples in this document are meant only as guidance and should not be applied in a production environment.

Use case illustration

To demonstrate a real-world example, OpenDocMan and HaloENGINE API are used, and requests and responses are shown in the API method section. In this manual, each method is outlined briefly, and its requests and responses are captured using the Postman tool.

OpenDocMan, an open-source document management system (DMS), communicates with the HaloENGINE API using a reverse proxy. However, depending on the business requirements, you can integrate your Document Management System using an intermediate reverse proxy, customization, or middleware application (such as MuleSoft). Using the HaloENGINE API methods, a file is encrypted when downloaded from OpenDocMan and decrypted when uploaded to OpenDocMan.

Quick Start

The following high-level steps describe how to get started with HaloENGINE and expose the APIs.

Step 1: Install and configure the HaloENGINE and HaloENGINE Service as described in the following chapters “Installing the HaloENGINE Service” and “Installing the HaloENGINE”.
Step 2: Import the license with the HaloENGINE API enabled in the admin portal.
Step 3: Server Certificate Authentication. Select one of the following approaches for authentication.
Self-signed Certificate: A minor configuration change is necessary on the client side. Download the server certificate (HaloENGINEServer.cer) from the HaloENGINE Admin portal and manually install it on the client machine in the Trusted Root Certification Authorities.
Company Owned Signed Certificate: If you already have a certificate, you can import it into the admin portal. Make sure your company's Root CA is installed in Trusted Root Certification Authorities. In this case, there is no need to install the server certificate (HaloENGINEServer.cer) on your client machine.  For more details, please refer to the section “Phase 1. Certificate Configuration”.
Step 4: Set classification engine. This step comprises creating profiles, schema, and action rules based on the needs of your business. Please refer to the chapter “Setting Up Classification Engine”.

Requirements

The HaloENGINE requirements are listed in the table below.

Components	Details
Operating System	Supported only in Microsoft Windows Server 2022 and above. Latest Windows system updates installed.
Supported browser version	The most recent versions of Microsoft Edge, Chrome, and Firefox are supported by the HaloENGINE Admin portal.

Requirements

API Reference

Host/Base URL

Base URL	`https://{servername}:{port}/haloengine-server`
Endpoint description	`https://{servername}:{port}/haloengine-server/halosdk`

Base URL

Using the above URL, the "halosdk" API is accessible.

The following variables should be replaced with values for your system.

{server} corresponds to the server's name or IP address of your server.
{port} is the port number on which the server runs.

Resource Methods Description

Typically, an API will have multiple endpoints associated with the same resource. Every resource is exposed via a URL. You can obtain the URL of every resource by obtaining access to the API Root Endpoint.

Method	URL
GET	`/GetVersion`
POST	`/GetRequiredMetaDataTypes`
POST	`/GetActionForm`
POST	`/ExecuteActionForm`
POST	`/DecryptFileAndFetchLabel`
POST	`/SendPLMAuditLogData`

Endpoints

GetVersion

Purpose	Gets information about the HaloENGINE version installed on a server at the client site.
Request method	GET
Input Request	`https://{servername}:{port}/haloengine-server/halosdk/GetVersion`

GetVersion details

Postman Example

The following example is demonstrated using Postman tool and the HaloENGINE API to obtain data.

Request

CODE

GET https://10.41.14.69:8746/haloengine-server/halosdk/GetVersion

Response

A successful request returns the following information: Status code: 200. The response body is in plain text format containing the version number of the HaloENGINE.

CODE

6.8.0.0

The response indicates that HaloENGINE is alive and its version is 6.8.0.0.

OpenDocMan Example

The following example is demonstrated using OpenDocMan through a reverse proxy with the HaloENGINE API, with the results displayed in Postman tool.

Request

CODE

GET https://10.41.14.69:8746/haloengine-server/halosdk/GetVersion

Response

CODE

6.8.0.0

The response indicates that the HaloENGINE is alive and its version is 6.8.0.0.

GetRequiredMetaDataTypes

Purpose	Retrieves the necessary metadata types configured on the server in the customer environment.
Request method	POST
Input Request	`https://{servername}:{port}/haloengine-server/halosdk/GetRequiredMetaDataTypes`

GetRequiredMetaDataTypes details

Postman Example

The following example is demonstrated using Postman tool and the HaloENGINE API to obtain data.

Prerequisite: The HaloENGINE API system type does not currently have any built-in metadata; hence, new metadata can be created using Custom metadata. Please refer to the section “Custom metadata”.

Request

The request is sent in the Body-XML format with the following parameters:

customer_id - Indicates which customer ID the HaloENGINE is using.
system_id - Indicates the unique system ID of a client system.
system_type - Indicates the client system type.

CODE

<id>
	<customer_id>HaloAPI</customer_id>
	<system_id>RESTclient</system_id>
	<system_type>HaloENGINE_API</system_type>
</id>

Response

A successful request returns the following information: Status code: 200

Response to this request:

In the response, the metadata added in the HaloENGINE admin portal will be displayed.

CODE

[user_group, work_in_progress, folder, review, release, project]

OpenDocMan Example

The following example is demonstrated using OpenDocMan through a reverse proxy with the HaloENGINE API, with the results displayed in Postman tool.

Request

The request is sent in the Body-XML format with the following parameters:

CODE

<id>
	<customer_id>halo_customer</customer_id>
	<system_id>HaloengineClient</system_id>
	<system_type>HaloENGINE_API</system_type>
</id>

Response

A successful request returns the following information: Status code: 200

Response to this request:

CODE

[file_type, folder_name, lifecycle_name]

GetActionForm

There are three options in "Owner Configuration": Service (default), Static email, and User. You can set it up on the HaloENGINE admin portal. Note: In the case of static email, enter the user's email address in the admin portal. To learn how to configure Owner Configuration, refer to the section “Owner Configuration”.

Owner Configuration - User option

When you choose User in the HaloENGINE admin portal, the request results in true (<user_email_needed>true</user_email_needed>), therefore when executing ExecuteActionForm, you must enter the author's email ID.

Purpose	Determine whether to encrypt or decrypt a file.
Request method	POST
Input Request	`https://{servername}:{port}/haloengine-server/halosdk/GetActionForm`

GetActionForm details

Postman Example

The following example is demonstrated using Postman tool and the HaloENGINE API to obtain data.

Request

A multipart/form-data request is sent with the following parameters:

Key: customerIdentification (Text as Type)

Description: Indicates the customer's details (customer_id, system_id, and system_type) that HaloENGINE uses.

Value: The value should look similar to the following:

CODE

<id>
	<customer_id>HaloAPI</customer_id>
	<system_id>RESTclient</system_id>
	<system_type>HaloENGINE_API</system_type>
</id>

Key: metadata (Text as Type)

Description: Indicates the metadata provided to decide the appropriate action.

Value: The value should look similar to the following.

CODE

<metadata>
	<!--Optional:-->
	<general_metadata>
		<!--Optional:-->
		<simple_value>
			<!--Zero or more repetitions:-->
			<entry>
				<!--Optional:-->
				<key>user_name</key>
				<!--Zero or more repetitions:-->
				<value>john</value>
			</entry>
		</simple_value>
		<!--Optional:-->
		<complex_value>
			<!--Zero or more repetitions:-->
			<entry>
				<type>data</type>
				<key>project</key>
				<!--1 or more repetitions:-->
				<values>?</values>
			</entry>
		</complex_value>
	</general_metadata>
</metadata>

Response

A successful request returns the following information: Status code: 200

Response to this request:

CODE

--uuid:3c3e23eb-0225-4b65-893c-677e8ff8b10d
Content-Type: text/plain
Content-Transfer-Encoding: binary
Content-ID: <simMode>
Content-Disposition: form-data; name="simMode"

false
--uuid:3c3e23eb-0225-4b65-893c-677e8ff8b10d
Content-Type: text/plain
Content-Transfer-Encoding: binary
Content-ID: <labelVendor>
Content-Disposition: form-data; name="labelVendor"

NONE
--uuid:3c3e23eb-0225-4b65-893c-677e8ff8b10d
Content-Type: application/xml
Content-Transfer-Encoding: binary
Content-ID: <action>
Content-Disposition: form-data; name="action"


            <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
            <ns2:action xmlns:ns2="http://interfaces.central.halocore.secude.com">
                <value>LABEL</value>
                <value>AUDIT</value>
            </ns2:action>
--uuid:3c3e23eb-0225-4b65-893c-677e8ff8b10d
Content-Type: application/xml
Content-Transfer-Encoding: binary
Content-ID: <authorMode>
Content-Disposition: form-data; name="authorMode"


                <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
                <ns2:author_mode xmlns:ns2="http://interfaces.central.halocore.secude.com">
                    <user_email_needed>false</user_email_needed>
                    <static_email></static_email>
                </ns2:author_mode>
--uuid:3c3e23eb-0225-4b65-893c-677e8ff8b10d
Content-Type: text/xml
Content-Transfer-Encoding: binary
Content-ID: <classification>
Content-Disposition: form-data; name="classification"


                    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
                    <classification version="1.0">
                        <class name="Default">
                            <displayNames>
                                <displayName locale="en_US" name="Default"/>
                            </displayNames>
                            <properties>
                                <property name="Sensitivity" dataType="listValue">
                                    <displayNames>
                                        <displayName locale="en_US" name="Sensitivity"/>
                                    </displayNames>
                                    <values>
                                        <listValue name="Secret">
                                            <displayNames>
                                                <displayName locale="en_US" name="Secret"/>
                                            </displayNames>
                                        </listValue>
                                    </values>
                                </property>
                            </properties>
                        </class>
                    </classification>

--uuid:3c3e23eb-0225-4b65-893c-677e8ff8b10d
Content-Type: application/xml
Content-Transfer-Encoding: binary
Content-ID: <template>
Content-Disposition: form-data; name="template"


                        <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
                        <ns2:template xmlns:ns2="http://interfaces.central.halocore.secude.com">
                            <guid>99f1473d-74f4-47ca-9843-e735f94fa797</guid>
                            <template_name>HCAD Secret</template_name>
                        </ns2:template>
--uuid:3c3e23eb-0225-4b65-893c-677e8ff8b10d--

OpenDocMan Example

The following example is demonstrated using OpenDocMan through a reverse proxy with the HaloENGINE API, with the results displayed in Postman tool.

Request

A multipart/form-data request is sent with the following parameters:

Key: customerIdentification (Text as Type)

Description: Indicates the customer's details (customer_id, system_id, and system_type) that HaloENGINE uses.

Value: The value should look similar to the following:

CODE

<id>
	<customer_id>halo_customer</customer_id>
	<system_id>HaloengineClient</system_id>
	<system_type>HaloENGINE_API</system_type>
</id>

Key: metadata (Text as Type)

Description: Indicates the metadata provided to decide the appropriate action.

Value: The value should look similar to the following.

CODE

<metadata>
	<general_metadata>
		<simple_value
			
			<entry>
				<key>user_name</key>
				<value>john</value
			
			</entry>
		</simple_value>
		<complex_value>
			<entry
				
				<type>data</type>
				<key>project</key>
				<values>?</values>
			</entry>
		</complex_value>
	</general_metadata>
</metadata>

Response

A successful request returns the following information: Status code: 200

Response to this request:

CODE

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:template xmlns:ns2="http://interfaces.central.halocore.secude.com">
		<guid>d7e95033-e7f1-4218-8941-7d60d8e9cf69</guid>
		<template_name>CADSecured</template_name>
</ns2:template>

ExecuteActionForm

Purpose	Executes the determined action retrieved by GetActionForm.
Request method	POST
Input Request	`https://{servername}:{port}/haloengine-server/halosdk/ExecuteActionForm`

ExecuteActionForm details

Postman Example

The following example is demonstrated using Postman tool and the HaloENGINE API to obtain data.

Request for Encryption

Prerequisite: When you select the User option in "Owner Configuration", you must input an email address in the author field.

A multipart/form-data request is sent with the following parameters:

Key: customerIdentification (Text as Type)

Description: Indicates the customer's details (customer_id, system_id, and system_type) that HaloENGINE uses.

Value: The value should look similar to the following.

CODE

<id>
	<customer_id>HaloAPI</customer_id>
	<system_id>RESTclient</system_id>
	<system_type>HaloENGINE_API</system_type>
</id>

Key: action (Text as Type)

Description: Indicates what action should be taken on the file (LABEL/UNPROTECT/AUDIT).

Value

CODE

<action>
	<!--Zero or more repetitions:-->
	<value>LABEL</value>
</action>

Key: template (Text as Type)

Description: If the action is to label, it indicates the template to use.

Value: The value should look similar to the following.

CODE

<template>
	<!--Optional:-->
	<guid>99f1473d-74f4-47ca-9843-e735f94fa797</guid>
	<template_name>HCAD Secret</template_name>
</template>

Key: extendedTags (Text as Type)

Description: Indicates additional metadata that can be included while downloading a file.

Value: The value should look similar to the following.

CODE

<extended_tags>
	<!--Zero or more repetitions:-->
	<extended_tags>
		<key></key>
		<!--Optional:-->
		<value>username</value>
	</extended_tags>
</extended_tags>

Key: author (Text as Type)

Description: This indicates who owns the exported document. This field is applicable only when the User option is selected in the admin portal. Note: If you selected User in the admin portal, please provide the author's email address. The following is an example of the default Service option. Thus, no author is added.

Value: The value should look similar to the following.

CODE

<author>?</author>

Key: file_size (Text as Type)

Description: Indicates the file size in bytes.

Value: The value should look similar to the following.

CODE

Key: file (File as Type). Browse and choose a file.

Description: Indicates which file is currently being used.

Value: The value should look similar to the following.

CODE

BOM.txt

Key: classification (Text as Type)

Description: Indicates the sensitivity setting.

Value: The value should look similar to the following.

CODE

<classification>?<classification>

Response for Encryption

A successful request returns the following information: Status code: 200

Response to this request: Protected content will also be included in the response body.

JSON

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:applied_action
	xmlns:ns2="http://interfaces.central.halocore.secude.com">
	<fileProtected>true</fileProtected>
	<fileLabeled>true</fileLabeled>
	<fileDecrypted>false</fileDecrypted>
	<already_protected>false</already_protected>
</ns2:applied_action>

The .pfile extension shows that the action was successfully performed on the file.

Request for Decryption

To decrypt a file, use the same parameters as in the Request for Encryption, with the exception that the “action key” must be "Unprotect" and the “file key” must be a protected file, as shown below.

Key: action (Text as Type)

Description: If the action is to unprotect, it specifies which template should be used.

Value: The value should look similar to the following.

CODE

<action>
	<!--Zero or more repetitions:-->
	<value>UNPROTECT</value>
</action>

Key: file (File as Type). Browse and choose a protected file.

Description: Indicates which file is currently being used.

Value: The value should look similar to the following.

CODE

BOM.ptxt

Response for Decryption

Response to this request: Unprotected content will also be included in the response body.

CODE

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:applied_action
	xmlns:ns2="http://interfaces.central.halocore.secude.com">
	<fileProtected>false</fileProtected>
	<fileLabeled>false</fileLabeled>
	<fileDecrypted>true</fileDecrypted>
	<already_protected>true</already_protected>
</ns2:applied_action>

The protected file has been decrypted successfully in the above example.

OpenDocMan Example

The following example is demonstrated using OpenDocMan through a reverse proxy with the HaloENGINE API, with the results displayed in Postman tool.

Request for Encryption

A multipart/form-data request is sent with the following parameters:

Key: customerIdentification(Text as Type)

Description: Indicates the customer's details (customer_id, system_id, and system_type) that HaloENGINE uses.

Value: The value should look similar to the following:

CODE

<id>
	<customer_id>halo_customer</customer_id>
	<system_id>HaloengineClient</system_id>
	<system_type>HaloENGINE_API</system_type>
</id>

Key: action (Text as Type)

Description: Indicates what action should be taken on the file (LABEL/UNPROTECT/AUDIT).

Value: The value should look similar to the following.

CODE

<action>
	<!--Zero or more repetitions:-->
	<value>LABEL</value>
</action>

Key: template (Text as Type)

Description: If the action is to label, it indicates the template to use.

Value: The value should look similar to the following

CODE

<template>
	<!--Optional:-->
	<guid>d7e95033-e7f1-4218-8941-7d60d8e9cf69</guid>
	<template_name>CADSecured</template_name>
</template>

Key: extendedTags (Text as Type)

Description: Indicates additional metadata that can be included while downloading a file.

Value: The value should look similar to the following.

CODE

<extended_tags>
	<key/>
	<value>""</value>
</extended_tags>

Key: author(Text as Type)

Description: The following is an example of the default Service option. Thus, no author is added.

Value: The value should look similar to the following.

CODE

<author>?</author>

Key: file_size(Text as Type)

Description: Indicates the file size in bytes.

Value: The value should look similar to the following.

CODE

Key: file (File as Type)

Description: Indicates which file is currently being used.

Value: The value should look similar to the following.

CODE

Checklist.txt

Key: classification(Text as Type)

Description: Indicates the sensitivity setting.

Value: The value should look similar to the following.

CODE

<classification>?<classification>

Response for Encryption

A successful request returns the following information: Status code: 200

Response to this request: Protected content will also be included in the response body.

CODE

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:applied_action
	xmlns:ns2="http://interfaces.central.halocore.secude.com">
	<fileProtected>true</fileProtected>
	<fileLabeled>true</fileLabeled>
	<fileDecrypted>false</fileDecrypted>
	<already_protected>false</already_protected>
</ns2:applied_action>

The .pfile extension shows that the action was successfully performed on the file.

Request for Decryption

To decrypt a file, use the same parameters as in the Request for Encryption, with the exception that the action key must be "Unprotect" and the file key must be a protected file, as shown below.

Key: action (Text as Type)

Description: If the action is to unprotect, it specifies which template should be used.

Value: The value should look similar to the following.

CODE

<action>
	<!--Zero or more repetitions:-->
	<value>UNPROTECT</value>
</action>

Key: file (File as Type)

Description: Indicates which file is currently being used.

Value: The value should look similar to the following.

CODE

Checklist.ptxt

Response for Decryption

Response to this request: Unprotected content will also be included in the response body.

CODE

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:applied_action
	xmlns:ns2="http://interfaces.central.halocore.secude.com">
	<fileProtected>false</fileProtected>
	<fileLabeled>false</fileLabeled>
	<fileDecrypted>true</fileDecrypted>
	<already_protected>true</already_protected>
</ns2:applied_action>

The protected file has been decrypted successfully in the above example.

DecryptFileAndFetchLabel

Purpose	Decrypts an encrypted file and returns the label information that was used to encrypt the file.
Request method	POST
Input Request	`https://{servername}:{port}/haloengine-server/halosdk/DecryptFileAndFetchLabel`

DecryptFileAndFetchLabel details

Let's imagine a business use case in which a watermark needs to be added to a protected file.

The process of adding a watermark to a protected file involves decrypting it and then applying the same label. This can be achieved by using this method to identify the label applied to the file and then decrypting it.

Postman Example

The following example is demonstrated using Postman tool and the HaloENGINE API to obtain data.

Request for Decryption

A multipart/form-data request is sent with the following parameters:

Key: customerIdentification (Text as Type)

Description: Indicates the customer's details (customer_id, system_id, and system_type) that HaloENGINE uses.

Value: The value should look similar to the following.

CODE

<id>
	<customer_id>HaloAPI</customer_id>
	<system_id>RESTclient</system_id>
	<system_type>HaloENGINE_API</system_type>
</id>

Key: metadata (Text as Type)

Description: Indicates the metadata provided to decide the appropriate action.

Value: The value should look similar to the following.

CODE

<metadata>
	<!--Optional:-->
	<general_metadata></general_metadata>
</metadata>

Key: file_size (Text as Type)

Description: Indicates the file size in bytes.

Value: The value should look similar to the following.

CODE

Key: file (File as Type). Browse and choose a file.

Description: Indicates which file is currently being used.

Value: The value should look similar to the following.

CODE

BOM.ptxt

Key: classification (Text as Type)

Description: Indicates the sensitivity setting.

Value: The value should look similar to the following.

CODE

<classification>?<classification>

Response for Decryption

Response to this request: Unprotected content and label information will be sent in the response body as multipart/form-data.

CODE

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:applied_action
	xmlns:ns2="http://interfaces.central.halocore.secude.com">
	<fileProtected>false</fileProtected>
	<fileLabeled>false</fileLabeled>
	<fileDecrypted>true</fileDecrypted>
	<already_protected>true</already_protected>
</ns2:applied_action>

---
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:template
	xmlns:ns2="http://interfaces.central.halocore.secude.com">
	<guid>99f1473d-74f4-47ca-9843-e735f94fa797</guid>
	<template_name>HCAD Secret</template_name>
</ns2:template>

The protected file has been decrypted successfully in the above example.

OpenDocMan Example

The following example is demonstrated using OpenDocMan through a reverse proxy with the HaloENGINE API, with the results displayed in Postman tool.

Request for Decryption

A multipart/form-data request is sent with the following parameters:

Key: customerIdentification (Text as Type)

Description: Indicates the customer's details (customer_id, system_id, and system_type) that HaloENGINE uses.

Value: The value should look similar to the following.

CODE

<id>
	<customer_id>halo_customer</customer_id>
	<system_id>HaloengineClient</system_id>
	<system_type>HaloENGINE_API</system_type>
</id>

Key: metadata (Text as Type)

Description: Indicates the metadata provided to decide the appropriate action.

Value: The value should look similar to the following.

CODE

<metadata>
	<!--Optional:-->
	<general_metadata></general_metadata>
</metadata>

Key: file_size (Text as Type)

Description: Indicates the file size in bytes.

Value: The value should look similar to the following.

CODE

Key: file (File as Type). Browse and choose a file.

Description: Indicates which file is currently being used.

Value: The value should look similar to the following.

CODE

Checklist.ptxt

Key: classification (Text as Type)

Description: Indicates the sensitivity setting.

Value: The value should look similar to the following.

CODE

<classification>?<classification>

Response for Decryption

Response to this request: Unprotected content and label information will be sent in the response body as multipart/form-data.

CODE

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:applied_action
	xmlns:ns2="http://interfaces.central.halocore.secude.com">
	<fileProtected>false</fileProtected>
	<fileLabeled>false</fileLabeled>
	<fileDecrypted>true</fileDecrypted>
	<already_protected>true</already_protected>
</ns2:applied_action>

---
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:template
	xmlns:ns2="http://interfaces.central.halocore.secude.com">
	<guid>99f1473d-74f4-47ca-9843-e735f94fa797</guid>
	<template_name>CADSecured</template_name>
</ns2:template>

The protected file has been decrypted successfully in the above example.

SendAuditLogData

Purpose	Sends audit log to the server.
Request method	POST
Input Request	`https://{servername}:{port}/haloengine-server/halosdk/SendAuditLogData`

SendAuditLogData details

The following example is demonstrated using Postman and the HaloENGINE API to obtain data.

Request

A multipart/form-data request is sent with the following parameters:

Key: customerIdentification (Text as Type)

Description: Indicates the customer's details (customer_id, system_id, and system_type) that HaloENGINE uses.

Value: The value should look similar to the following.

CODE

<id>
	<customer_id>HaloAPI</customer_id>
	<system_id>RESTclient</system_id>
	<system_type>HaloENGINE_API</system_type>
</id

Key: logInfo (Text as Type)

Description: Indicates the timestamp when the event occurred.

Value: The value should look similar to the following.

CODE

<log_info>
	<utc_time_stamp>2021-02-23T23:01:00+05:00</utc_time_stamp>
	<!--Optional:-->
	<time_zone>-1</time_zone>
	<!--Optional:-->
	<logID>loginID1</logID>
</log_info>

Key: userInfo (Text as Type)

Description: Indicates the user details.

Value: The value should look similar to the following.

CODE

<user_info>
	<user_name>john</user_name>
	<!--Optional:-->
	<user_type>john</user_type>
	<user_email>john@halosecude.onmicrosoft.com</user_email>
</user_info>

Key: fileInfo (Text as Type)

Description: Indicates the file details.

Value: The value should look similar to the following.

CODE

<file_info>
	<!--Optional:-->
	<file_name></file_name>
	<!--Optional:-->
	<file_path>C:\</file_path>
	<!--Optional:-->
	<file_type>txt</file_type>
	<file_protected_before>false</file_protected_before>
	<size_original>4445</size_original>
	<size_download>444448</size_download>
</file_info>

Key: resultedDecision (Text as Type)

Description: Indicates the action that was taken on the file.

Value: The value should look similar to the following.

CODE

<resulted_decision>
	<fileBlocked>false</fileBlocked>
	<fileLabeled>false</fileLabeled>
	<fileProtected>false</fileProtected>
	<unprotected>true</unprotected>
	<fileBlocked>true</fileBlocked>
	<unlabeled>true</unlabeled>
	<!--Optional:-->
	<policy_name>HCAD Secret</policy_name>
	<!--Optional:-->
	<policy_id>99f1473d-74f4-47ca-9843-e735f94fa797</policy_id>
	<!--Optional:-->
	<classification>
		<by_user>
			<?xml version="1.0" encoding="UTF-8"?>
			<classification version="1.0">
				<class name="DB">
					<displayNames>
						<displayName locale="en_US" name="Local Configuration"/>
					</displayNames>
					<properties>
						<property name="C_IPADDR" dataType="stringValue" valueType="simple">
							<displayNames>
								<displayName locale="en_US" name="IP Address"/>
							</displayNames>
							<values></values>
						</property>
						<property name="C_LOGID" dataType="stringValue" valueType="simple">
							<displayNames>
								<displayName locale="en_US" name="Log ID"/>
							</displayNames>
							<values></values>
						</property>
						<property name="C_TABS" dataType="stringValue" valueType="simple">
							<displayNames>
								<displayName locale="en_US" name="Table/View Names"/>
							</displayNames>
							<values></values>
						</property>
						<property name="C_TSTMP" dataType="stringValue" valueType="simple">
							<displayNames>
								<displayName locale="en_US" name="Time Stamp"/>
							</displayNames>
							<values></values>
						</property>
						<property name="C_TCODE" dataType="stringValue" valueType="simple">
							<displayNames>
								<displayName locale="en_US" name="Transaction Code"/>
							</displayNames>
							<values></values>
						</property>
						<property name="C_UNAME" dataType="stringValue" valueType="simple">
							<displayNames>
								<displayName locale="en_US" name="User Name"/>
							</displayNames>
							<values></values>
						</property>
						<property name="C_WDAPPL" dataType="stringValue" valueType="simple">
							<displayNames>
								<displayName locale="en_US" name="WD Application"/>
							</displayNames>
							<values></values>
						</property>
						<property name="SENS" dataType="listValue" valueType="simple">
							<displayNames>
								<displayName locale="en_US" name="Sensitivity_1"/>
							</displayNames>
							<values>
								<listValue name="CONF">
									<displayNames>
										<displayName locale="en_US" name="Confidential"/>
									</displayNames>
								</listValue>
							</values>
						</property>
						<property name="DOM" dataType="listValue" valueType="simple">
							<displayNames>
								<displayName locale="en_US" name="Domain"/>
							</displayNames>
							<values>
								<listValue name="LOG">
									<displayNames>
										<displayName locale="en_US" name="Logistics"/>
									</displayNames>
								</listValue>
							</values>
						</property>
					</properties>
				</class>
			</classification>
		</by_user>
		<by_system>
			<?xml version="1.0" encoding="UTF-8"?>
			<classification version="1.0">
				<class name="DB">
					<displayNames>
						<displayName locale="en_US" name="Local Configuration"/>
					</displayNames>
					<properties>
						<property name="C_IPADDR" dataType="stringValue" valueType="simple">
							<displayNames>
								<displayName locale="en_US" name="IP Address"/>
							</displayNames>
							<values></values>
						</property>
						<property name="C_LOGID" dataType="stringValue" valueType="simple">
							<displayNames>
								<displayName locale="en_US" name="Log ID"/>
							</displayNames>
							<values></values>
						</property>
						<property name="C_TABS" dataType="stringValue" valueType="simple">
							<displayNames>
								<displayName locale="en_US" name="Table/View Names"/>
							</displayNames>
							<values></values>
						</property>
						<property name="C_TSTMP" dataType="stringValue" valueType="simple">
							<displayNames>
								<displayName locale="en_US" name="Time Stamp"/>
							</displayNames>
							<values></values>
						</property>
						<property name="C_TCODE" dataType="stringValue" valueType="simple">
							<displayNames>
								<displayName locale="en_US" name="Transaction Code"/>
							</displayNames>
							<values></values>
						</property>
						<property name="C_UNAME" dataType="stringValue" valueType="simple">
							<displayNames>
								<displayName locale="en_US" name="User Name"/>
							</displayNames>
							<values></values>
						</property>
						<property name="C_WDAPPL" dataType="stringValue" valueType="simple">
							<displayNames>
								<displayName locale="en_US" name="WD Application"/>
							</displayNames>
							<values></values>
						</property>
						<property name="SENS" dataType="listValue" valueType="simple">
							<displayNames>
								<displayName locale="en_US" name="Sensitivity_1"/>
							</displayNames>
							<values>
								<listValue name="CONF">
									<displayNames>
										<displayName locale="en_US" name="Confidential"/>
									</displayNames>
								</listValue>
							</values>
						</property>
						<property name="DOM" dataType="listValue" valueType="simple">
							<displayNames>
								<displayName locale="en_US" name="Domain"/>
							</displayNames>
							<values>
								<listValue name="LOG">
									<displayNames>
										<displayName locale="en_US" name="Logistics"/>
									</displayNames>
								</listValue>
							</values>
						</property>
					</properties>
				</class>
			</classification>
		</by_system>
	</classification>
	<aborted_by_system>false</aborted_by_system>
	<aborted_by_user>false</aborted_by_user>
	<error>false</error>
	<!--Optional:-->
	<sim_mode>false</sim_mode>
	<!--Zero or more repetitions:-->
	<extended_tags>
		<key>Key1</key>
		<!--Optional:-->
		<value>Value1</value>
	</extended_tags>
</resulted_decision>

Key: plmContextInfo (Text as Type)

Description: Indicates the PLM server information (source).

Value: The value should look similar to the following.

CODE

<plm_context_info>
	<!--Optional:-->
	<event_type>user download</event_type>
	<browser_client>false</browser_client>
	<!--Zero or more repetitions:-->
	<pre_process_info>
		<!--Optional:-->
		<type>sample</type>
		<key>ABC</key>
		<value>12345</value>
	</pre_process_info>
	<!--Zero or more repetitions:-->
	<attributes>
		<!--Optional:-->
		<type>Attr1</type>
		<key>project_name</key>
		<value>CMS_Turbo_Engine</value>
	</attributes>
	<!--Optional:-->
	<document_id>1222</document_id>
	<!--Optional:-->
	<document_number>222</document_number>
	<!--Optional:-->
	<document_type>1</document_type>
	<!--Optional:-->
	<document_part>j</document_part>
	<!--Optional:-->
	<document_version>00</document_version>
	<!--Optional:-->
	<view_only>false</view_only>
	<!--Optional:-->
	<dms_process>false</dms_process>
</plm_context_info>

Key: plmDestInfo (Text as Type)

Description: Indicates the destination, such as which client the data was downloaded from.

Value: The value should look similar to the following.

CODE

<plm_destination_info>
	<!--Zero or more repetitions:-->
	<destination_attributes>
		<!--Optional:-->
		<type>Dest</type>
		<key>client_ip</key>
		<value>10.41.14.69</value>
	</destination_attributes>
	<!--Optional:-->
	<browser>Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/112.0.0.0 Safari/537.36</browser>
	<!--Optional:-->
	<hostname>ABC</hostname>
	<!--Optional:-->
	<ipaddress>10.41.14.69</ipaddress>
	<!--Optional:-->
	<operating_system>WIN10</operating_system>
</plm_destination_info>

Response

A successful request returns the following information: Status code: 200

Response to this request: In boolean value

CODE

true

The log is sent to the server.

Error Handling

An unsuccessful request returns a response code other than 200. If you receive a null response, you may need to review the input.

Status Code

Sample Message

Description

400 BAD_REQUEST

Monitor feature is not enabled

The Monitor feature is not activated in the portal.

401 UNAUTHORIZED

Unauthorized client attempting to access the endpoint. The page cannot be viewed because the client type is not licensed for it. Please contact the administrator.

Attempted to connect to an unlicensed endpoint.

406

NOT_ACCEPTABLE

The System type is wrong. Please contact the administrator.

When any of the values, such as customer ID, system ID, or system type, are incorrect it will be stated in the error message.

Error Codes