> For the complete documentation index, see [llms.txt](https://documentation.efalia.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.efalia.com/api-reference/efalia-process-api/actor.md). # Actor This represents an Actor. It can be a real user, an agent or an organizational unit. For every request where an Actor or a list of Actor is expected, the following query parameters can be set:\ \ show\ This parameter can take a comma separated list of the following values: `all` (default), `managers`, `roles`, `units`, `delegations`, `available`.
hide\ This parameter can take a comma separated list of the same values as the `show` parameter. It is used to avoid fetching elements about the actor and improve speed.
simple\ If this parameter is set to `true`, only minimal information about the actor is retrieved. It has the same effect as setting the parameter `hide=all`. ## Get actor by Dn > Get an actor by its \`Dn\`.\ > \### Note\ > Get actor by dn is deprecated, you should use \/actor/{idOrDn}\ instead. ```json {"openapi":"3.0.0","info":{"title":"Efalia Process API","version":"6.36.1"},"tags":[{"name":"Actor","description":"This represents an Actor. It can be a real user, an agent or an organizational unit. For every\n request where an Actor or a list of Actor is expected, the following query parameters can be set:
\n
\n show
This parameter can take a comma separated list of the following values: `all` (default),\n `managers`, `roles`, `units`, `delegations`, `available`.
\n\n hide
This parameter can take a comma separated list of the same values as the `show` parameter. It is used to\n avoid fetching elements about the actor and improve speed.
\n\n simple
If this parameter is set to `true`, only minimal information about the actor is retrieved. It has the same effect\n as setting the parameter `hide=all`."}],"servers":[{"url":"http://{hostname}/{workeyContext}/api/","variables":{"hostname":{"default":"localhost:8080","description":"Hostname and port of the Workey server"},"workeyContext":{"default":"workey","description":"Name of the running context of Workey"}}}],"security":[{"Basic":[]},{"Bearer":[]},{"ApiKey":[],"ApiKeyImpersonate":[]}],"components":{"securitySchemes":{"Basic":{"type":"http","scheme":"basic","description":"Value: Basic {encode username:password}"},"Bearer":{"type":"http","scheme":"bearer","description":"Value: Bearer {jwt}"},"ApiKey":{"type":"apiKey","name":"X-API-KEY","in":"header","description":"API key defined in Process configuration."}},"schemas":{"Actor":{"allOf":[{"$ref":"#/components/schemas/WorkeyObject"},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ActorType"},"language":{"type":"string"},"manager":{"$ref":"#/components/schemas/ActorManager"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/Role"}},"units":{"type":"array","items":{"$ref":"#/components/schemas/Unit"}},"delegations":{"type":"array","items":{"$ref":"#/components/schemas/Delegation"}},"availableDocuments":{"type":"array","items":{"$ref":"#/components/schemas/AvailableDocument"}}}}]},"WorkeyObject":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}}},"ActorType":{"type":"string","enum":["AGENT","PERSON","UNIT","CUSTOMER"]},"ActorManager":{"type":"object","properties":{"processes":{"type":"array","items":{"$ref":"#/components/schemas/Process"}},"workflow":{"type":"boolean"},"units":{"type":"array","items":{"$ref":"#/components/schemas/Unit"}}}},"Process":{"allOf":[{"$ref":"#/components/schemas/WorkeyObject"},{"type":"object","properties":{"date":{"type":"string","format":"date-time"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/Role"}},"documentTypes":{"type":"array","items":{"$ref":"#/components/schemas/WorkeyObject"}},"active":{"type":"boolean"},"version":{"type":"integer"}}}]},"Role":{"allOf":[{"$ref":"#/components/schemas/WorkeyObject"},{"type":"object","properties":{"processType":{"$ref":"#/components/schemas/Process"},"agent":{"type":"boolean"}}}]},"Unit":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"type":{"$ref":"#/components/schemas/ActorType"},"dn":{"type":"string"},"cn":{"type":"string"},"childrenUnits":{"type":"array","items":{"$ref":"#/components/schemas/Unit"}}}},"Delegation":{"type":"object","properties":{"role":{"$ref":"#/components/schemas/WorkeyObject"},"documentType":{"$ref":"#/components/schemas/WorkeyObject"},"from":{"$ref":"#/components/schemas/WorkeyObject"},"processType":{"$ref":"#/components/schemas/WorkeyObject"},"delegates":{"type":"array","items":{"$ref":"#/components/schemas/WorkeyObject"}},"status":{"type":"string"},"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"}}},"AvailableDocument":{"type":"object","properties":{"processType":{"$ref":"#/components/schemas/WorkeyObject"},"documentType":{"$ref":"#/components/schemas/WorkeyObject"},"role":{"$ref":"#/components/schemas/WorkeyObject"},"url":{"type":"string"}}},"RestMessage":{"type":"object","properties":{"code":{"type":"integer"},"error":{"type":"boolean"},"message":{"type":"string"},"cause":{"$ref":"#/components/schemas/ErrorCause"}}},"ErrorCause":{"type":"object","properties":{"className":{"type":"string"},"method":{"type":"string"},"line":{"type":"integer"},"stackTrace":{"type":"object"}}}},"responses":{"WorkeyUnauthorized":{"description":"Unauthorized Workey access error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestMessage"}}}},"WorkeyError":{"description":"Unexpected Workey Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestMessage"}}}}}},"paths":{"/actor":{"get":{"summary":"Get actor by Dn","description":"Get an actor by its `Dn`.\n### Note\nGet actor by dn is deprecated, you should use /actor/{idOrDn} instead.","operationId":"ActorByDn","deprecated":true,"tags":["Actor"],"parameters":[{"name":"dn","in":"query","schema":{"type":"string"},"required":false,"description":"The `Dn` of the actor. If it not specified, current logged actor is the returned as resource."}],"responses":{"200":{"description":"The matching actor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Actor"}}}},"401":{"$ref":"#/components/responses/WorkeyUnauthorized"},"555":{"$ref":"#/components/responses/WorkeyError"}}}}}} ``` ## Create actor by Dn > Create an actor by its \`Dn\`.\ > \### Note\ > Experimental feature. ```json {"openapi":"3.0.0","info":{"title":"Efalia Process API","version":"6.36.1"},"tags":[{"name":"Actor","description":"This represents an Actor. It can be a real user, an agent or an organizational unit. For every\n request where an Actor or a list of Actor is expected, the following query parameters can be set:
\n
\n show
This parameter can take a comma separated list of the following values: `all` (default),\n `managers`, `roles`, `units`, `delegations`, `available`.
\n\n hide
This parameter can take a comma separated list of the same values as the `show` parameter. It is used to\n avoid fetching elements about the actor and improve speed.
\n\n simple
If this parameter is set to `true`, only minimal information about the actor is retrieved. It has the same effect\n as setting the parameter `hide=all`."}],"servers":[{"url":"http://{hostname}/{workeyContext}/api/","variables":{"hostname":{"default":"localhost:8080","description":"Hostname and port of the Workey server"},"workeyContext":{"default":"workey","description":"Name of the running context of Workey"}}}],"security":[{"Basic":[]},{"Bearer":[]},{"ApiKey":[],"ApiKeyImpersonate":[]}],"components":{"securitySchemes":{"Basic":{"type":"http","scheme":"basic","description":"Value: Basic {encode username:password}"},"Bearer":{"type":"http","scheme":"bearer","description":"Value: Bearer {jwt}"},"ApiKey":{"type":"apiKey","name":"X-API-KEY","in":"header","description":"API key defined in Process configuration."}},"schemas":{"Actor":{"allOf":[{"$ref":"#/components/schemas/WorkeyObject"},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ActorType"},"language":{"type":"string"},"manager":{"$ref":"#/components/schemas/ActorManager"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/Role"}},"units":{"type":"array","items":{"$ref":"#/components/schemas/Unit"}},"delegations":{"type":"array","items":{"$ref":"#/components/schemas/Delegation"}},"availableDocuments":{"type":"array","items":{"$ref":"#/components/schemas/AvailableDocument"}}}}]},"WorkeyObject":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}}},"ActorType":{"type":"string","enum":["AGENT","PERSON","UNIT","CUSTOMER"]},"ActorManager":{"type":"object","properties":{"processes":{"type":"array","items":{"$ref":"#/components/schemas/Process"}},"workflow":{"type":"boolean"},"units":{"type":"array","items":{"$ref":"#/components/schemas/Unit"}}}},"Process":{"allOf":[{"$ref":"#/components/schemas/WorkeyObject"},{"type":"object","properties":{"date":{"type":"string","format":"date-time"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/Role"}},"documentTypes":{"type":"array","items":{"$ref":"#/components/schemas/WorkeyObject"}},"active":{"type":"boolean"},"version":{"type":"integer"}}}]},"Role":{"allOf":[{"$ref":"#/components/schemas/WorkeyObject"},{"type":"object","properties":{"processType":{"$ref":"#/components/schemas/Process"},"agent":{"type":"boolean"}}}]},"Unit":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"type":{"$ref":"#/components/schemas/ActorType"},"dn":{"type":"string"},"cn":{"type":"string"},"childrenUnits":{"type":"array","items":{"$ref":"#/components/schemas/Unit"}}}},"Delegation":{"type":"object","properties":{"role":{"$ref":"#/components/schemas/WorkeyObject"},"documentType":{"$ref":"#/components/schemas/WorkeyObject"},"from":{"$ref":"#/components/schemas/WorkeyObject"},"processType":{"$ref":"#/components/schemas/WorkeyObject"},"delegates":{"type":"array","items":{"$ref":"#/components/schemas/WorkeyObject"}},"status":{"type":"string"},"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"}}},"AvailableDocument":{"type":"object","properties":{"processType":{"$ref":"#/components/schemas/WorkeyObject"},"documentType":{"$ref":"#/components/schemas/WorkeyObject"},"role":{"$ref":"#/components/schemas/WorkeyObject"},"url":{"type":"string"}}},"RestMessage":{"type":"object","properties":{"code":{"type":"integer"},"error":{"type":"boolean"},"message":{"type":"string"},"cause":{"$ref":"#/components/schemas/ErrorCause"}}},"ErrorCause":{"type":"object","properties":{"className":{"type":"string"},"method":{"type":"string"},"line":{"type":"integer"},"stackTrace":{"type":"object"}}}},"responses":{"WorkeyUnauthorized":{"description":"Unauthorized Workey access error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestMessage"}}}},"WorkeyError":{"description":"Unexpected Workey Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestMessage"}}}}}},"paths":{"/actor":{"post":{"summary":"Create actor by Dn","description":"Create an actor by its `Dn`.\n### Note\nExperimental feature.","operationId":"createActor","deprecated":false,"tags":["Actor"],"parameters":[{"name":"actorDn","in":"query","schema":{"type":"string"},"required":true,"description":"The ``Dn`` of the actor."}],"responses":{"200":{"description":"The created actor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Actor"}}}},"401":{"$ref":"#/components/responses/WorkeyUnauthorized"},"404":{"description":"Create actor with Dn \"{dnParam}\" impossible"},"555":{"$ref":"#/components/responses/WorkeyError"}}}}}} ``` ## Actor logout > Invalidate the current session for this actor. ```json {"openapi":"3.0.0","info":{"title":"Efalia Process API","version":"6.36.1"},"tags":[{"name":"Actor","description":"This represents an Actor. It can be a real user, an agent or an organizational unit. For every\n request where an Actor or a list of Actor is expected, the following query parameters can be set:
\n
\n show
This parameter can take a comma separated list of the following values: `all` (default),\n `managers`, `roles`, `units`, `delegations`, `available`.
\n\n hide
This parameter can take a comma separated list of the same values as the `show` parameter. It is used to\n avoid fetching elements about the actor and improve speed.
\n\n simple
If this parameter is set to `true`, only minimal information about the actor is retrieved. It has the same effect\n as setting the parameter `hide=all`."}],"servers":[{"url":"http://{hostname}/{workeyContext}/api/","variables":{"hostname":{"default":"localhost:8080","description":"Hostname and port of the Workey server"},"workeyContext":{"default":"workey","description":"Name of the running context of Workey"}}}],"security":[{"Basic":[]},{"Bearer":[]},{"ApiKey":[],"ApiKeyImpersonate":[]}],"components":{"securitySchemes":{"Basic":{"type":"http","scheme":"basic","description":"Value: Basic {encode username:password}"},"Bearer":{"type":"http","scheme":"bearer","description":"Value: Bearer {jwt}"},"ApiKey":{"type":"apiKey","name":"X-API-KEY","in":"header","description":"API key defined in Process configuration."}},"schemas":{"RestMessage":{"type":"object","properties":{"code":{"type":"integer"},"error":{"type":"boolean"},"message":{"type":"string"},"cause":{"$ref":"#/components/schemas/ErrorCause"}}},"ErrorCause":{"type":"object","properties":{"className":{"type":"string"},"method":{"type":"string"},"line":{"type":"integer"},"stackTrace":{"type":"object"}}}},"responses":{"WorkeyUnauthorized":{"description":"Unauthorized Workey access error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestMessage"}}}},"WorkeyError":{"description":"Unexpected Workey Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestMessage"}}}}}},"paths":{"/actor/logout":{"get":{"summary":"Actor logout","description":"Invalidate the current session for this actor.","operationId":"actorLogout","deprecated":false,"tags":["Actor"],"responses":{"200":{"description":"Actor logged out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestMessage"}}}},"401":{"$ref":"#/components/responses/WorkeyUnauthorized"},"555":{"$ref":"#/components/responses/WorkeyError"}}}}}} ``` ## Get actor preference > Get an actor preference by one key. ```json {"openapi":"3.0.0","info":{"title":"Efalia Process API","version":"6.36.1"},"tags":[{"name":"Actor","description":"This represents an Actor. It can be a real user, an agent or an organizational unit. For every\n request where an Actor or a list of Actor is expected, the following query parameters can be set:
\n
\n show
This parameter can take a comma separated list of the following values: `all` (default),\n `managers`, `roles`, `units`, `delegations`, `available`.
\n\n hide
This parameter can take a comma separated list of the same values as the `show` parameter. It is used to\n avoid fetching elements about the actor and improve speed.
\n\n simple
If this parameter is set to `true`, only minimal information about the actor is retrieved. It has the same effect\n as setting the parameter `hide=all`."}],"servers":[{"url":"http://{hostname}/{workeyContext}/api/","variables":{"hostname":{"default":"localhost:8080","description":"Hostname and port of the Workey server"},"workeyContext":{"default":"workey","description":"Name of the running context of Workey"}}}],"security":[{"Basic":[]},{"Bearer":[]},{"ApiKey":[],"ApiKeyImpersonate":[]}],"components":{"securitySchemes":{"Basic":{"type":"http","scheme":"basic","description":"Value: Basic {encode username:password}"},"Bearer":{"type":"http","scheme":"bearer","description":"Value: Bearer {jwt}"},"ApiKey":{"type":"apiKey","name":"X-API-KEY","in":"header","description":"API key defined in Process configuration."}},"schemas":{"ActorPreference":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"prefKey":{"type":"string"},"prefValue":{"type":"string"},"rank":{"type":"integer"},"actorId":{"type":"integer","format":"int64"},"version":{"type":"integer","format":"int64"},"localized":{"type":"boolean"},"selected":{"type":"boolean"}}},"RestMessage":{"type":"object","properties":{"code":{"type":"integer"},"error":{"type":"boolean"},"message":{"type":"string"},"cause":{"$ref":"#/components/schemas/ErrorCause"}}},"ErrorCause":{"type":"object","properties":{"className":{"type":"string"},"method":{"type":"string"},"line":{"type":"integer"},"stackTrace":{"type":"object"}}}},"responses":{"WorkeyUnauthorized":{"description":"Unauthorized Workey access error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestMessage"}}}},"WorkeyError":{"description":"Unexpected Workey Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestMessage"}}}}}},"paths":{"/actor/preferences":{"get":{"summary":"Get actor preference","description":"Get an actor preference by one key.","operationId":"Preference","deprecated":true,"tags":["Actor"],"parameters":[{"name":"key","in":"query","schema":{"type":"string"},"required":false,"description":"The name of the preference to retrieve."}],"responses":{"200":{"description":"The matching preference for this actor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActorPreference"}}}},"401":{"$ref":"#/components/responses/WorkeyUnauthorized"},"555":{"$ref":"#/components/responses/WorkeyError"}}}}}} ``` ## Save actor preference > Save an actor preference as a key and value pair. ```json {"openapi":"3.0.0","info":{"title":"Efalia Process API","version":"6.36.1"},"tags":[{"name":"Actor","description":"This represents an Actor. It can be a real user, an agent or an organizational unit. For every\n request where an Actor or a list of Actor is expected, the following query parameters can be set:
\n
\n show
This parameter can take a comma separated list of the following values: `all` (default),\n `managers`, `roles`, `units`, `delegations`, `available`.
\n\n hide
This parameter can take a comma separated list of the same values as the `show` parameter. It is used to\n avoid fetching elements about the actor and improve speed.
\n\n simple
If this parameter is set to `true`, only minimal information about the actor is retrieved. It has the same effect\n as setting the parameter `hide=all`."}],"servers":[{"url":"http://{hostname}/{workeyContext}/api/","variables":{"hostname":{"default":"localhost:8080","description":"Hostname and port of the Workey server"},"workeyContext":{"default":"workey","description":"Name of the running context of Workey"}}}],"security":[{"Basic":[]},{"Bearer":[]},{"ApiKey":[],"ApiKeyImpersonate":[]}],"components":{"securitySchemes":{"Basic":{"type":"http","scheme":"basic","description":"Value: Basic {encode username:password}"},"Bearer":{"type":"http","scheme":"bearer","description":"Value: Bearer {jwt}"},"ApiKey":{"type":"apiKey","name":"X-API-KEY","in":"header","description":"API key defined in Process configuration."}},"schemas":{"ActorPreference":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"prefKey":{"type":"string"},"prefValue":{"type":"string"},"rank":{"type":"integer"},"actorId":{"type":"integer","format":"int64"},"version":{"type":"integer","format":"int64"},"localized":{"type":"boolean"},"selected":{"type":"boolean"}}},"RestMessage":{"type":"object","properties":{"code":{"type":"integer"},"error":{"type":"boolean"},"message":{"type":"string"},"cause":{"$ref":"#/components/schemas/ErrorCause"}}},"ErrorCause":{"type":"object","properties":{"className":{"type":"string"},"method":{"type":"string"},"line":{"type":"integer"},"stackTrace":{"type":"object"}}}},"responses":{"WorkeyUnauthorized":{"description":"Unauthorized Workey access error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestMessage"}}}},"WorkeyError":{"description":"Unexpected Workey Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestMessage"}}}}}},"paths":{"/actor/preferences":{"post":{"summary":"Save actor preference","description":"Save an actor preference as a key and value pair.","operationId":"SavePreference","deprecated":true,"tags":["Actor"],"parameters":[{"name":"preferenceKey","in":"query","schema":{"type":"string"},"required":true,"description":"The name of the preference to save."},{"name":"preferenceValue","in":"query","schema":{"type":"string"},"required":true,"description":"The value of the preference to save."}],"responses":{"200":{"description":"The saved preference","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActorPreference"}}}},"401":{"$ref":"#/components/responses/WorkeyUnauthorized"},"555":{"$ref":"#/components/responses/WorkeyError"}}}}}} ``` ## Delete actor preference > Delete an actor preference. ```json {"openapi":"3.0.0","info":{"title":"Efalia Process API","version":"6.36.1"},"tags":[{"name":"Actor","description":"This represents an Actor. It can be a real user, an agent or an organizational unit. For every\n request where an Actor or a list of Actor is expected, the following query parameters can be set:
\n
\n show
This parameter can take a comma separated list of the following values: `all` (default),\n `managers`, `roles`, `units`, `delegations`, `available`.
\n\n hide
This parameter can take a comma separated list of the same values as the `show` parameter. It is used to\n avoid fetching elements about the actor and improve speed.
\n\n simple
If this parameter is set to `true`, only minimal information about the actor is retrieved. It has the same effect\n as setting the parameter `hide=all`."}],"servers":[{"url":"http://{hostname}/{workeyContext}/api/","variables":{"hostname":{"default":"localhost:8080","description":"Hostname and port of the Workey server"},"workeyContext":{"default":"workey","description":"Name of the running context of Workey"}}}],"security":[{"Basic":[]},{"Bearer":[]},{"ApiKey":[],"ApiKeyImpersonate":[]}],"components":{"securitySchemes":{"Basic":{"type":"http","scheme":"basic","description":"Value: Basic {encode username:password}"},"Bearer":{"type":"http","scheme":"bearer","description":"Value: Bearer {jwt}"},"ApiKey":{"type":"apiKey","name":"X-API-KEY","in":"header","description":"API key defined in Process configuration."}},"schemas":{"RestMessage":{"type":"object","properties":{"code":{"type":"integer"},"error":{"type":"boolean"},"message":{"type":"string"},"cause":{"$ref":"#/components/schemas/ErrorCause"}}},"ErrorCause":{"type":"object","properties":{"className":{"type":"string"},"method":{"type":"string"},"line":{"type":"integer"},"stackTrace":{"type":"object"}}}},"responses":{"WorkeyUnauthorized":{"description":"Unauthorized Workey access error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestMessage"}}}},"WorkeyError":{"description":"Unexpected Workey Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestMessage"}}}}}},"paths":{"/actor/preferences/{preferenceId}":{"delete":{"summary":"Delete actor preference","description":"Delete an actor preference.","operationId":"ActorPreference","deprecated":true,"tags":["Actor"],"parameters":[{"name":"preferenceId","in":"path","required":true,"schema":{"type":"string"},"description":"The Id of the preference to delete."}],"responses":{"200":{"description":"Preference #{preferenceId} removed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestMessage"}}}},"401":{"$ref":"#/components/responses/WorkeyUnauthorized"},"555":{"$ref":"#/components/responses/WorkeyError"}}}}}} ``` ## Replace actor > Replace an actor by another, according to a replacement policy.\ > \ > \Workflow Manager\\ > \### Note\ > This method is currently \not working\ in v.6.6.0.\ > See also \Actors - Replace Actor\ for a similar operation.\
```json {"openapi":"3.0.0","info":{"title":"Efalia Process API","version":"6.36.1"},"tags":[{"name":"Actor","description":"This represents an Actor. It can be a real user, an agent or an organizational unit. For every\n request where an Actor or a list of Actor is expected, the following query parameters can be set:
\n
\n show
This parameter can take a comma separated list of the following values: `all` (default),\n `managers`, `roles`, `units`, `delegations`, `available`.
\n\n hide
This parameter can take a comma separated list of the same values as the `show` parameter. It is used to\n avoid fetching elements about the actor and improve speed.
\n\n simple
If this parameter is set to `true`, only minimal information about the actor is retrieved. It has the same effect\n as setting the parameter `hide=all`."}],"servers":[{"url":"http://{hostname}/{workeyContext}/api/","variables":{"hostname":{"default":"localhost:8080","description":"Hostname and port of the Workey server"},"workeyContext":{"default":"workey","description":"Name of the running context of Workey"}}}],"security":[{"Basic":[]},{"Bearer":[]},{"ApiKey":[],"ApiKeyImpersonate":[]}],"components":{"securitySchemes":{"Basic":{"type":"http","scheme":"basic","description":"Value: Basic {encode username:password}"},"Bearer":{"type":"http","scheme":"bearer","description":"Value: Bearer {jwt}"},"ApiKey":{"type":"apiKey","name":"X-API-KEY","in":"header","description":"API key defined in Process configuration."}},"schemas":{"RestMessage":{"type":"object","properties":{"code":{"type":"integer"},"error":{"type":"boolean"},"message":{"type":"string"},"cause":{"$ref":"#/components/schemas/ErrorCause"}}},"ErrorCause":{"type":"object","properties":{"className":{"type":"string"},"method":{"type":"string"},"line":{"type":"integer"},"stackTrace":{"type":"object"}}}},"responses":{"WorkeyUnauthorized":{"description":"Unauthorized Workey access error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestMessage"}}}},"WorkeyError":{"description":"Unexpected Workey Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestMessage"}}}}}},"paths":{"/actor/replace/{oldActor}/{newActor}/{replacementPolicy}":{"post":{"summary":"Replace actor","description":"Replace an actor by another, according to a replacement policy.\n\nWorkflow Manager\n### Note\nThis method is currently not working in v.6.6.0.\n See also Actors - Replace Actor for a similar operation.
","operationId":"ReplaceActor","deprecated":false,"tags":["Actor"],"parameters":[{"name":"oldActor","in":"path","required":true,"schema":{"type":"string"},"description":"The actor to replace. If it is a number, it is considered as the actor Id,\n otherwise it is considered as the actor name."},{"name":"newActor","in":"path","required":true,"schema":{"type":"string"},"description":"The new actor. It must be the name of the actor."},{"name":"replacementPolicy","in":"path","required":true,"schema":{"type":"string"},"description":"The policy code to use, it can be \"full\", \"relay\" or \"quit\".\n
\n
full
The actor replaced is completly substitued by the new one. No trace of the old actor are left on the server (except for some persistent history track).
\n
relay
With this policy, the old actor will stay active in the system, while the replacing actor will be able to do everything the old actor could.
\n
quit
The old actor will quit the system after the transfer of everything to the replacing actor.
"}],"responses":{"200":{"description":"Replaced \"{oldActor}\" by \"{newActor}\" with policy #{replacementPolicy}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestMessage"}}}},"401":{"$ref":"#/components/responses/WorkeyUnauthorized"},"404":{"description":"No actor found with Id or Dn \"{oldActor}\""},"555":{"$ref":"#/components/responses/WorkeyError"}}}}}} ``` ## Get actor setting > Get an actor setting by one key. ```json {"openapi":"3.0.0","info":{"title":"Efalia Process API","version":"6.36.1"},"tags":[{"name":"Actor","description":"This represents an Actor. It can be a real user, an agent or an organizational unit. For every\n request where an Actor or a list of Actor is expected, the following query parameters can be set:
\n
\n show
This parameter can take a comma separated list of the following values: `all` (default),\n `managers`, `roles`, `units`, `delegations`, `available`.
\n\n hide
This parameter can take a comma separated list of the same values as the `show` parameter. It is used to\n avoid fetching elements about the actor and improve speed.
\n\n simple
If this parameter is set to `true`, only minimal information about the actor is retrieved. It has the same effect\n as setting the parameter `hide=all`."}],"servers":[{"url":"http://{hostname}/{workeyContext}/api/","variables":{"hostname":{"default":"localhost:8080","description":"Hostname and port of the Workey server"},"workeyContext":{"default":"workey","description":"Name of the running context of Workey"}}}],"security":[{"Basic":[]},{"Bearer":[]},{"ApiKey":[],"ApiKeyImpersonate":[]}],"components":{"securitySchemes":{"Basic":{"type":"http","scheme":"basic","description":"Value: Basic {encode username:password}"},"Bearer":{"type":"http","scheme":"bearer","description":"Value: Bearer {jwt}"},"ApiKey":{"type":"apiKey","name":"X-API-KEY","in":"header","description":"API key defined in Process configuration."}},"schemas":{"ActorSetting":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"settingKey":{"type":"string"},"settingValue":{"type":"string"},"actorId":{"type":"integer","format":"int64"},"version":{"type":"integer","format":"int64"},"localized":{"type":"boolean"},"selected":{"type":"boolean"}}},"RestMessage":{"type":"object","properties":{"code":{"type":"integer"},"error":{"type":"boolean"},"message":{"type":"string"},"cause":{"$ref":"#/components/schemas/ErrorCause"}}},"ErrorCause":{"type":"object","properties":{"className":{"type":"string"},"method":{"type":"string"},"line":{"type":"integer"},"stackTrace":{"type":"object"}}}},"responses":{"WorkeyUnauthorized":{"description":"Unauthorized Workey access error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestMessage"}}}},"WorkeyError":{"description":"Unexpected Workey Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestMessage"}}}}}},"paths":{"/actor/settings":{"get":{"summary":"Get actor setting","description":"Get an actor setting by one key.","operationId":"Settings","deprecated":false,"tags":["Actor"],"parameters":[{"name":"key","in":"query","schema":{"type":"string"},"required":false,"description":"The name of the setting to retrieve."}],"responses":{"200":{"description":"The matching setting for this actor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActorSetting"}}}},"401":{"$ref":"#/components/responses/WorkeyUnauthorized"},"404":{"description":"No Settings found for key #{key}"},"555":{"$ref":"#/components/responses/WorkeyError"}}}}}} ``` ## Save actor setting > Save an actor setting as a key and value pair. ```json {"openapi":"3.0.0","info":{"title":"Efalia Process API","version":"6.36.1"},"tags":[{"name":"Actor","description":"This represents an Actor. It can be a real user, an agent or an organizational unit. For every\n request where an Actor or a list of Actor is expected, the following query parameters can be set:
\n
\n show
This parameter can take a comma separated list of the following values: `all` (default),\n `managers`, `roles`, `units`, `delegations`, `available`.
\n\n hide
This parameter can take a comma separated list of the same values as the `show` parameter. It is used to\n avoid fetching elements about the actor and improve speed.
\n\n simple
If this parameter is set to `true`, only minimal information about the actor is retrieved. It has the same effect\n as setting the parameter `hide=all`."}],"servers":[{"url":"http://{hostname}/{workeyContext}/api/","variables":{"hostname":{"default":"localhost:8080","description":"Hostname and port of the Workey server"},"workeyContext":{"default":"workey","description":"Name of the running context of Workey"}}}],"security":[{"Basic":[]},{"Bearer":[]},{"ApiKey":[],"ApiKeyImpersonate":[]}],"components":{"securitySchemes":{"Basic":{"type":"http","scheme":"basic","description":"Value: Basic {encode username:password}"},"Bearer":{"type":"http","scheme":"bearer","description":"Value: Bearer {jwt}"},"ApiKey":{"type":"apiKey","name":"X-API-KEY","in":"header","description":"API key defined in Process configuration."}},"schemas":{"ActorSetting":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"settingKey":{"type":"string"},"settingValue":{"type":"string"},"actorId":{"type":"integer","format":"int64"},"version":{"type":"integer","format":"int64"},"localized":{"type":"boolean"},"selected":{"type":"boolean"}}},"RestMessage":{"type":"object","properties":{"code":{"type":"integer"},"error":{"type":"boolean"},"message":{"type":"string"},"cause":{"$ref":"#/components/schemas/ErrorCause"}}},"ErrorCause":{"type":"object","properties":{"className":{"type":"string"},"method":{"type":"string"},"line":{"type":"integer"},"stackTrace":{"type":"object"}}}},"responses":{"WorkeyUnauthorized":{"description":"Unauthorized Workey access error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestMessage"}}}},"WorkeyError":{"description":"Unexpected Workey Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestMessage"}}}}}},"paths":{"/actor/settings":{"post":{"summary":"Save actor setting","description":"Save an actor setting as a key and value pair.","operationId":"SaveSettings","deprecated":false,"tags":["Actor"],"parameters":[{"name":"settingKey","in":"query","schema":{"type":"string"},"required":true,"description":"The name of the setting to save."},{"name":"settingValue","in":"query","schema":{"type":"string"},"required":true,"description":"The value of the setting to save."}],"responses":{"200":{"description":"The saved setting","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActorSetting"}}}},"401":{"$ref":"#/components/responses/WorkeyUnauthorized"},"555":{"$ref":"#/components/responses/WorkeyError"}}}}}} ``` ## Get actor by Dn or Id > Get an Actor by their \`Id\` or their \`Dn\`. ```json {"openapi":"3.0.0","info":{"title":"Efalia Process API","version":"6.36.1"},"tags":[{"name":"Actor","description":"This represents an Actor. It can be a real user, an agent or an organizational unit. For every\n request where an Actor or a list of Actor is expected, the following query parameters can be set:
\n
\n show
This parameter can take a comma separated list of the following values: `all` (default),\n `managers`, `roles`, `units`, `delegations`, `available`.
\n\n hide
This parameter can take a comma separated list of the same values as the `show` parameter. It is used to\n avoid fetching elements about the actor and improve speed.
\n\n simple
If this parameter is set to `true`, only minimal information about the actor is retrieved. It has the same effect\n as setting the parameter `hide=all`."}],"servers":[{"url":"http://{hostname}/{workeyContext}/api/","variables":{"hostname":{"default":"localhost:8080","description":"Hostname and port of the Workey server"},"workeyContext":{"default":"workey","description":"Name of the running context of Workey"}}}],"security":[{"Basic":[]},{"Bearer":[]},{"ApiKey":[],"ApiKeyImpersonate":[]}],"components":{"securitySchemes":{"Basic":{"type":"http","scheme":"basic","description":"Value: Basic {encode username:password}"},"Bearer":{"type":"http","scheme":"bearer","description":"Value: Bearer {jwt}"},"ApiKey":{"type":"apiKey","name":"X-API-KEY","in":"header","description":"API key defined in Process configuration."}},"schemas":{"Actor":{"allOf":[{"$ref":"#/components/schemas/WorkeyObject"},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ActorType"},"language":{"type":"string"},"manager":{"$ref":"#/components/schemas/ActorManager"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/Role"}},"units":{"type":"array","items":{"$ref":"#/components/schemas/Unit"}},"delegations":{"type":"array","items":{"$ref":"#/components/schemas/Delegation"}},"availableDocuments":{"type":"array","items":{"$ref":"#/components/schemas/AvailableDocument"}}}}]},"WorkeyObject":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}}},"ActorType":{"type":"string","enum":["AGENT","PERSON","UNIT","CUSTOMER"]},"ActorManager":{"type":"object","properties":{"processes":{"type":"array","items":{"$ref":"#/components/schemas/Process"}},"workflow":{"type":"boolean"},"units":{"type":"array","items":{"$ref":"#/components/schemas/Unit"}}}},"Process":{"allOf":[{"$ref":"#/components/schemas/WorkeyObject"},{"type":"object","properties":{"date":{"type":"string","format":"date-time"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/Role"}},"documentTypes":{"type":"array","items":{"$ref":"#/components/schemas/WorkeyObject"}},"active":{"type":"boolean"},"version":{"type":"integer"}}}]},"Role":{"allOf":[{"$ref":"#/components/schemas/WorkeyObject"},{"type":"object","properties":{"processType":{"$ref":"#/components/schemas/Process"},"agent":{"type":"boolean"}}}]},"Unit":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"type":{"$ref":"#/components/schemas/ActorType"},"dn":{"type":"string"},"cn":{"type":"string"},"childrenUnits":{"type":"array","items":{"$ref":"#/components/schemas/Unit"}}}},"Delegation":{"type":"object","properties":{"role":{"$ref":"#/components/schemas/WorkeyObject"},"documentType":{"$ref":"#/components/schemas/WorkeyObject"},"from":{"$ref":"#/components/schemas/WorkeyObject"},"processType":{"$ref":"#/components/schemas/WorkeyObject"},"delegates":{"type":"array","items":{"$ref":"#/components/schemas/WorkeyObject"}},"status":{"type":"string"},"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"}}},"AvailableDocument":{"type":"object","properties":{"processType":{"$ref":"#/components/schemas/WorkeyObject"},"documentType":{"$ref":"#/components/schemas/WorkeyObject"},"role":{"$ref":"#/components/schemas/WorkeyObject"},"url":{"type":"string"}}},"RestMessage":{"type":"object","properties":{"code":{"type":"integer"},"error":{"type":"boolean"},"message":{"type":"string"},"cause":{"$ref":"#/components/schemas/ErrorCause"}}},"ErrorCause":{"type":"object","properties":{"className":{"type":"string"},"method":{"type":"string"},"line":{"type":"integer"},"stackTrace":{"type":"object"}}}},"responses":{"WorkeyUnauthorized":{"description":"Unauthorized Workey access error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestMessage"}}}},"WorkeyError":{"description":"Unexpected Workey Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestMessage"}}}}}},"paths":{"/actor/{idOrDn}":{"get":{"summary":"Get actor by Dn or Id","description":"Get an Actor by their `Id` or their `Dn`.","operationId":"ActorByDnOrId","deprecated":false,"tags":["Actor"],"parameters":[{"name":"idOrDn","in":"path","required":true,"schema":{"type":"string"},"description":"If it is a number, it is considered as the actor `Id`,\n otherwise it is considered as the actor name."}],"responses":{"200":{"description":"The matching actor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Actor"}}}},"401":{"$ref":"#/components/responses/WorkeyUnauthorized"},"555":{"$ref":"#/components/responses/WorkeyError"}}}}}} ``` ## Updates actor data by Dn or Id > Update an Actor by their \`Id\` or their \`Dn\`.\ > \ > \Workflow Manager\\ > \### Note\ > Experimental feature (Only updates language). ```json {"openapi":"3.0.0","info":{"title":"Efalia Process API","version":"6.36.1"},"tags":[{"name":"Actor","description":"This represents an Actor. It can be a real user, an agent or an organizational unit. For every\n request where an Actor or a list of Actor is expected, the following query parameters can be set:
\n
\n show
This parameter can take a comma separated list of the following values: `all` (default),\n `managers`, `roles`, `units`, `delegations`, `available`.
\n\n hide
This parameter can take a comma separated list of the same values as the `show` parameter. It is used to\n avoid fetching elements about the actor and improve speed.
\n\n simple
If this parameter is set to `true`, only minimal information about the actor is retrieved. It has the same effect\n as setting the parameter `hide=all`."}],"servers":[{"url":"http://{hostname}/{workeyContext}/api/","variables":{"hostname":{"default":"localhost:8080","description":"Hostname and port of the Workey server"},"workeyContext":{"default":"workey","description":"Name of the running context of Workey"}}}],"security":[{"Basic":[]},{"Bearer":[]},{"ApiKey":[],"ApiKeyImpersonate":[]}],"components":{"securitySchemes":{"Basic":{"type":"http","scheme":"basic","description":"Value: Basic {encode username:password}"},"Bearer":{"type":"http","scheme":"bearer","description":"Value: Bearer {jwt}"},"ApiKey":{"type":"apiKey","name":"X-API-KEY","in":"header","description":"API key defined in Process configuration."}},"schemas":{"ActorData":{"type":"object","properties":{"isWorkflowManager":{"type":"boolean"},"language":{"type":"string"}}},"Actor":{"allOf":[{"$ref":"#/components/schemas/WorkeyObject"},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ActorType"},"language":{"type":"string"},"manager":{"$ref":"#/components/schemas/ActorManager"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/Role"}},"units":{"type":"array","items":{"$ref":"#/components/schemas/Unit"}},"delegations":{"type":"array","items":{"$ref":"#/components/schemas/Delegation"}},"availableDocuments":{"type":"array","items":{"$ref":"#/components/schemas/AvailableDocument"}}}}]},"WorkeyObject":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}}},"ActorType":{"type":"string","enum":["AGENT","PERSON","UNIT","CUSTOMER"]},"ActorManager":{"type":"object","properties":{"processes":{"type":"array","items":{"$ref":"#/components/schemas/Process"}},"workflow":{"type":"boolean"},"units":{"type":"array","items":{"$ref":"#/components/schemas/Unit"}}}},"Process":{"allOf":[{"$ref":"#/components/schemas/WorkeyObject"},{"type":"object","properties":{"date":{"type":"string","format":"date-time"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/Role"}},"documentTypes":{"type":"array","items":{"$ref":"#/components/schemas/WorkeyObject"}},"active":{"type":"boolean"},"version":{"type":"integer"}}}]},"Role":{"allOf":[{"$ref":"#/components/schemas/WorkeyObject"},{"type":"object","properties":{"processType":{"$ref":"#/components/schemas/Process"},"agent":{"type":"boolean"}}}]},"Unit":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"type":{"$ref":"#/components/schemas/ActorType"},"dn":{"type":"string"},"cn":{"type":"string"},"childrenUnits":{"type":"array","items":{"$ref":"#/components/schemas/Unit"}}}},"Delegation":{"type":"object","properties":{"role":{"$ref":"#/components/schemas/WorkeyObject"},"documentType":{"$ref":"#/components/schemas/WorkeyObject"},"from":{"$ref":"#/components/schemas/WorkeyObject"},"processType":{"$ref":"#/components/schemas/WorkeyObject"},"delegates":{"type":"array","items":{"$ref":"#/components/schemas/WorkeyObject"}},"status":{"type":"string"},"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"}}},"AvailableDocument":{"type":"object","properties":{"processType":{"$ref":"#/components/schemas/WorkeyObject"},"documentType":{"$ref":"#/components/schemas/WorkeyObject"},"role":{"$ref":"#/components/schemas/WorkeyObject"},"url":{"type":"string"}}},"RestMessage":{"type":"object","properties":{"code":{"type":"integer"},"error":{"type":"boolean"},"message":{"type":"string"},"cause":{"$ref":"#/components/schemas/ErrorCause"}}},"ErrorCause":{"type":"object","properties":{"className":{"type":"string"},"method":{"type":"string"},"line":{"type":"integer"},"stackTrace":{"type":"object"}}}},"responses":{"WorkeyUnauthorized":{"description":"Unauthorized Workey access error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestMessage"}}}},"WorkeyError":{"description":"Unexpected Workey Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestMessage"}}}}}},"paths":{"/actor/{idOrDn}":{"put":{"summary":"Updates actor data by Dn or Id","description":"Update an Actor by their `Id` or their `Dn`.\n\nWorkflow Manager\n### Note\nExperimental feature (Only updates language).","operationId":"setActorData","deprecated":false,"tags":["Actor"],"parameters":[{"name":"idOrDn","in":"path","required":true,"schema":{"type":"string"},"description":"If it is a number, it is considered as the actor ``Id``,\n otherwise it is considered as the actor name."}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActorData"}}}},"responses":{"200":{"description":"The updated actor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Actor"}}}},"401":{"$ref":"#/components/responses/WorkeyUnauthorized"},"555":{"$ref":"#/components/responses/WorkeyError"}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://documentation.efalia.com/api-reference/efalia-process-api/actor.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.