sonar-sync-departments

Synchronizes Logpresso Sonar department objects based on the input record. Departments present in the input record set are created or updated, and existing departments not present in the input are deleted.

When synchronizing department, employee, and department head information with an external HR system, you must run three commands in order: department, then employee, then department head. This command is the first of those three steps and does not synchronize the department head field, so you must synchronize employees with sonar-sync-employees and then assign department heads with sonar-sync-bosses.

Command properties

Property	Description
Command type	Processing query
Required permission	Administrator
License usage	N/A
Parallel execution	Not supported
Distributed execution	Runs on Control Node (reducer)

Syntax

... | sonar-sync-departments [run=BOOL]

Options

run=BOOL: Applies the synchronization for real only when specified as t. If not specified, nothing is actually applied, and only the action (action) to be performed and the expected result are previewed (a dry run).

Input fields

Field	Type	Required	Description
`dept_code`	string	Required	Department code. This value is used to match against existing departments to determine whether to create or update. If missing, an exception is thrown without further validation and the query is aborted
`dept_name`	string	Required	Department name. The parser's description marks this as required, but the source has no separate validation logic for it. If missing, it is not filtered out at the parsing or command stage and proceeds as is, but because the name column in the storage has a NOT NULL constraint, it fails at the storage stage when actually applied with `run=t`, and is output with `status=failure`
`parent_dept_code`	string	Optional	Parent department code. If no matching department can be found in the input record set or the existing department list, a separate notification (`notify`) record is output
`description`	string	Optional	Department description

Output fields

Field	Type	Description
`session`	string	A randomly generated unique session GUID identifier. Every record output from the same query run shares the same value
`action`	string	The action performed (or planned). One of `notify`, `create`, `update`, `delete`, `set_parent`, `unset_parent`
`status`	string	Output only when an actual application was attempted with `run=t`. `success` or `failure`
`dept_code`	string	Department code. Not output when `action=notify`
`dept_name`	string	Department name. Not output when `action=notify`
`dept_guid`	string	Department GUID (36 characters). Not output when `action=notify`
`params`	map	Details of the change. Always includes the `description` key, and when `action=set_parent` also includes `parent_guid` and `parent_name`; when a comparison with the previous state is possible, it additionally includes `old_name`, `old_parent_name`, and `old_parent_guid`. Not output when `action=notify`
`error`	string	Error message. Not output for records processed successfully

Error codes

Parsing errors

Error code	Message	Description
300160	No permission to sync	Run in a session without administrator permission

Runtime errors

N/A

Description

sonar-sync-departments synchronizes the entire department tree based on the input records. It reads the entire existing department list at the start of execution, and once all input records have arrived, processes them in the following order.

For each input record's dept_code, if it exists among the existing departments, an update action is registered by comparing whether the name or description changed; if it does not exist, a create action is registered.
Comparing the parent department link based on parent_dept_code, a set_parent action is registered if a parent department is newly assigned or changed, and an unset_parent action is registered if an existing parent department link is removed.
Any dept_code among the existing departments that is not present in the input record set is registered as a delete action.

If run=t is not specified, only the list of actions above is output as records, and nothing is actually changed (a dry run). You must specify run=t to actually create, update, or delete departments, in which case the processing result (success or failure) is also output in each record's status field. This command does not synchronize the department head (boss) field, so to assign a department head you must separately run the sonar-sync-bosses command.

When creating a department, to avoid dependency issues from parent department and department head assignment, the department is first created with only its name, code, and description, and the parent department link is then handled afterward as a set_parent action. If the department corresponding to parent_dept_code cannot be found in either the input record set or the existing department list, the create/update action already registered for that department is not canceled and proceeds as is, just without the parent department link; separately, a notify record is also output with a parent department code not found: <code> error message.

Examples

Preview the department list synchronization result (dry run)

json "[
  {'dept_code': '001000', 'dept_name': 'Business Division', 'description': 'Overall business management'},
  {'dept_code': '001100', 'dept_name': 'Sales Team', 'parent_dept_code': '001000', 'description': 'Domestic sales'}
]"
| sonar-sync-departments

Because the run option is not specified, nothing is actually applied, and only the planned actions such as create and set_parent are output.

Actually synchronize the department list

json "[
  {'dept_code': '001000', 'dept_name': 'Business Division', 'description': 'Overall business management'},
  {'dept_code': '001100', 'dept_name': 'Sales Team', 'parent_dept_code': '001000', 'description': 'Domestic sales'}
]"
| sonar-sync-departments run=t
| search status == "failure"

Specifies run=t to actually create, update, or delete departments, and filters to check only the failed records.

Change history

The sonar-sync-departments command is available in the Sonar 4.0 series starting with 4.0.2609.0, where the command previously provided by the Experimental app was built into Sonar core. On versions without the built-in command, install the Experimental app to use it.