Orchestrator user guide

Orchestrator Diagnostic Logs​

Enabling UiPath Orchestrator Diagnostic Logs​

Targets of the UiPath Orchestrator Diagnostic Logs​

• Could not create Quartz Job

• validation issues such as:
  • Invalid username/email address or password.
  • The machine name DOC is already taken
• business conflicts such as:
  • License expired!
  • The floating robot's session is already active on machine ROQADOCS06!
  • The robots already have pending jobs for this Process.
• not found exceptions such as:
  • QueueName1 does not exist.

Orchestrator Execution Logs​

Targets of the Orchestrator Execution Logs​

<target xsi:type="Database" name="database" connectionString="${ui-connection-strings:item=Default}" keepConnection="true">
 <commandText>
  insert into dbo.Logs (OrganizationUnitId, TenantId, TimeStamp, Level, WindowsIdentity, ProcessName, JobKey, Message, RawMessage)
  values (@organizationUnitId, @tenantId, @timeStamp, @level, @windowsIdentity, @processName, @jobId, @message, @rawMessage)
 </commandText>
  <parameter name="@organizationUnitId" layout="${event-properties:item=organizationUnitId}" />
  <parameter name="@tenantId" layout="${event-properties:item=tenantId}" />
  <parameter name="@timeStamp" layout="${date}" />
  <parameter name="@level" layout="${event-properties:item=levelOrdinal}" />
  <parameter name="@windowsIdentity" layout="${event-properties:item=windowsIdentity}" />
  <parameter name="@processName" layout="${event-properties:item=processName}" />
  <parameter name="@jobId" layout="${event-properties:item=jobId}" />
  <parameter name="@message" layout="${message}" />
  <parameter name="@rawMessage" layout="${event-properties:item=rawMessage}" />
</target>
 <logger name="Robot.*" writeTo="database" final="true" />
<target xsi:type="Database" name="database" connectionString="${ui-connection-strings:item=Default}" keepConnection="true">
 <commandText>
  insert into dbo.Logs (OrganizationUnitId, TenantId, TimeStamp, Level, WindowsIdentity, ProcessName, JobKey, Message, RawMessage)
  values (@organizationUnitId, @tenantId, @timeStamp, @level, @windowsIdentity, @processName, @jobId, @message, @rawMessage)
 </commandText>
  <parameter name="@organizationUnitId" layout="${event-properties:item=organizationUnitId}" />
  <parameter name="@tenantId" layout="${event-properties:item=tenantId}" />
  <parameter name="@timeStamp" layout="${date}" />
  <parameter name="@level" layout="${event-properties:item=levelOrdinal}" />
  <parameter name="@windowsIdentity" layout="${event-properties:item=windowsIdentity}" />
  <parameter name="@processName" layout="${event-properties:item=processName}" />
  <parameter name="@jobId" layout="${event-properties:item=jobId}" />
  <parameter name="@message" layout="${message}" />
  <parameter name="@rawMessage" layout="${event-properties:item=rawMessage}" />
</target>
 <logger name="Robot.*" writeTo="database" final="true" />

CREATE NONCLUSTERED INDEX [IX_Search] ON [dbo].[Logs]
(
[TenantId] ASC,
[OrganizationUnitId] ASC,
[Level] ASC,
[TimeStamp] DESC
)WITH (STATISTICS_NORECOMPUTE = OFF, DROP_EXISTING = OFF, ONLINE = OFF, OPTIMIZE_FOR_SEQUENTIAL_KEY = OFF) ON [PRIMARY]
GO
CREATE NONCLUSTERED INDEX [IX_Search] ON [dbo].[Logs]
(
[TenantId] ASC,
[OrganizationUnitId] ASC,
[Level] ASC,
[TimeStamp] DESC
)WITH (STATISTICS_NORECOMPUTE = OFF, DROP_EXISTING = OFF, ONLINE = OFF, OPTIMIZE_FOR_SEQUENTIAL_KEY = OFF) ON [PRIMARY]
GO

Elasticsearch Server​

For Elasticsearch versions lower than 8.0:​

<target name="robotElasticBuffer" xsi:type="BufferingWrapper" flushTimeout="5000">
<target xsi:type="ElasticSearch" name="robotElastic" uri="uritoelasticsearchnode" index="${event-properties:item=indexName}-${date:format=yyyy.MM}" documentType="logEvent" includeAllProperties="true" layout="${message}" excludedProperties="agentSessionId,tenantId,organizationId,indexName" />
</target>
</target>
<target name="robotElasticBuffer" xsi:type="BufferingWrapper" flushTimeout="5000">
<target xsi:type="ElasticSearch" name="robotElastic" uri="uritoelasticsearchnode" index="${event-properties:item=indexName}-${date:format=yyyy.MM}" documentType="logEvent" includeAllProperties="true" layout="${message}" excludedProperties="agentSessionId,tenantId,organizationId,indexName" />
</target>
</target>

For Elasticsearch versions 8.0 and higher:​

<target name="robotElasticBuffer" xsi:type="BufferingWrapper" flushTimeout="5000">
<target xsi:type="ElasticSearch" name="robotElastic" uri="uritoelasticsearchnode" index="${event-properties:item=indexName}-${date:format=yyyy.MM}" documentType="" enableApiVersioningHeader="true" includeAllProperties="true" layout="${message}" excludedProperties="agentSessionId,tenantId,organizationId,indexName" />
</target>
</target>
<target name="robotElasticBuffer" xsi:type="BufferingWrapper" flushTimeout="5000">
<target xsi:type="ElasticSearch" name="robotElastic" uri="uritoelasticsearchnode" index="${event-properties:item=indexName}-${date:format=yyyy.MM}" documentType="" enableApiVersioningHeader="true" includeAllProperties="true" layout="${message}" excludedProperties="agentSessionId,tenantId,organizationId,indexName" />
</target>
</target>

• documentType is empty.
• enableApiVersioningHeader is set to true.
  Note:

  The option to save robot logs to an Elasticsearch server only becomes effective once you configure it, and is not applied retroactively. This means that you will no longer have access to any logs that were already in the database at the time you configured the option, because logs can only be retrieved and displayed from a single destination.

X-PACK Authentication​

Username-and-password Authentication​

1. Configure the Elasticsearch server as follows:
   • Add the xpack.security.enabled setting to the elasticsearch.yml configuration file.
   • Set up a username and password.

2. Configure Orchestrator's UiPath.Orchestrator.dll.config file as follows:

• Option 1: If you do not use an NLog target, you need to configure the following parameters: Logs.Elasticsearch.Username and Logs.Elasticsearch.Password. Make sure their values match the Elasticsearch settings from Step 1.
• Option 2: If Logs.RobotLogs.ReadTarget is set to an NLog target (for example, robotElasticBuffer), and the Logs.Elasticsearch.Nodes setting is not specified, configure the target by adding the following: requireAuth="true" username="XPACKuser" password="p@$$w0rd". Make sure these parameter values match the Elasticsearch settings from Step 1.

<target name="robotElasticBuffer" xsi:type="BufferingWrapper" flushTimeout="5000">
        <target xsi:type="ElasticSearch" name="robotElastic" uri="" requireAuth="true" username="XPACKusername" password="p@$$w0rd" index="${event-properties:item=indexName}-${date:format=yyyy.MM}" documentType="logEvent" includeAllProperties="true" layout="${message}" excludedProperties="agentSessionId,tenantId,indexName" />
      </target>
<target name="robotElasticBuffer" xsi:type="BufferingWrapper" flushTimeout="5000">
        <target xsi:type="ElasticSearch" name="robotElastic" uri="" requireAuth="true" username="XPACKusername" password="p@$$w0rd" index="${event-properties:item=indexName}-${date:format=yyyy.MM}" documentType="logEvent" includeAllProperties="true" layout="${message}" excludedProperties="agentSessionId,tenantId,indexName" />
      </target>

• Option 3: If Logs.RobotLogs.ReadTarget is set to an NLog target ( for example, robotElasticBuffer), and an Elasticsearch node is specified via the Logs.Elasticsearch.Nodes setting, you need to explicitly configure it (as it overrides the NLog target settings), and make sure to also add the following: requireAuth="true" username="XPACKuser" password="p@$$w0rd". Make sure these parameter values match the Elasticsearch settings from Step 1.

OAuth2 Authentication​

1. Configure the Elasticsearch server as follows:

   1. Enable TLS (HTTPS) for the transport layer.
   2. Update the following settings in the elasticsearch.yml configuration file:
   • xpack.security.authc.token.enabled: true
   • xpack.security.enabled: true
   • xpack.security.authc.token.timeout - This settings is optional and controls for how long a token is valid. By default, its value is set to 20 minutes.

2. Update the following parameters in Orchestrator's UiPath.Orchestrator.dll.config file to reflect the settings you opted for at Step 1.
   • Logs.Elasticsearch.TlsEnabled = ”true” - By default, this parameter is set to true and ensures TLC (HTTPS) is enabled.
   • Logs.Elasticsearch.OAuthEnabled = ”true” - By default, this parameter is set to false. For more on this, see Logs.Elasticsearch.OAuthEnabled.
   • Logs.Elasticsearch.OAuthExpireInSeconds = ”1200” - This parameter is optional unless the default value of 1200 is changed in the Elasticsearch xpack.security.authc.token.timeout setting. This parameter must have the same value as in the Elasticsearch configuration. For more on this, see Logs.Elasticsearch.OAuthExpireInSeconds.
     Note:

     The first two steps help you configure a token-based authentication mechanism for reading logs. If you use NLog, an additional step is needed.

3. To enable OAuth2 for Nlog, make sure to also configure the following parameter in Orchestrator's UiPath.Orchestrator.dll.config file. Note that you must fill in the username and password for authentication in Elasticsearch because the initial token is generated based on those credentials.
   • OAuthEnabled = “true” - By default, it is set to false. For more on this, see the UiPath.Orchestrator.dll.config page.
     Important:

     If Logs.RobotLogs.ReadTarget is set to an NLog target (for example, robotElasticBuffer), and the Logs.Elasticsearch.Nodes setting is not specified, then the Logs.Elasticsearch.OAuthEnabled is filled from the NLog target configuration. Same logic is applied for username and password.

API key authentication​

1. Generate the API key by following these steps.
2. Store the API key as a secret in your Azure key vault.
3. Configure the following Nlog target parameters with your data, thus creating a connection between Orchestrator and your key vault which allows the key to be retrieved:
   assignment

   apiKeyEnabled="true"
   apiKeyProvider="AzureKeyVault"
   apiKeySecretName="<SecretName>"
   azureKeyVaultUri="<KeyVaultUri>"
   azureKeyVaultDirectoryId="<KeyVaultDirectoryId>"
   azureKeyVaultClientId="<KeyVaultClientId>"
   azureKeyVaultCertificateThumbprint="<KeyVaultCertificateThumbprint>"
   azureKeyVaultCertificateStoreLocation="CurrentUser/LocalMachine"
   apiKeyEnabled="true"
   apiKeyProvider="AzureKeyVault"
   apiKeySecretName="<SecretName>"
   azureKeyVaultUri="<KeyVaultUri>"
   azureKeyVaultDirectoryId="<KeyVaultDirectoryId>"
   azureKeyVaultClientId="<KeyVaultClientId>"
   azureKeyVaultCertificateThumbprint="<KeyVaultCertificateThumbprint>"
   azureKeyVaultCertificateStoreLocation="CurrentUser/LocalMachine"
   

• <SecretName> - the name you set for your API key in the key vault
• <KeyVaultUri> - the URI of your key vault
• <KeyVaultDirectoryId> - your key vault directory ID
• <KeyVaultClientId> - your key vault client ID
• <KeyVaultCertificateThumbprint> - the thumbprint of your key vault certificate
• CurrentUser/LocalMachine - the location where the certificate is stored