2024年7月

1 Technical Program

1.1 Plugin Overview

JIRA Sync data plugin (URANUS Sync), the use of API way, to achieve the mutual synchronization of data between different products as well as the use of view API to view the data in the product.

Support issue extension and display custom fields.

Currently, the plug-in supports configuration of the data source JIRA, rocketmq, rabbitmq, kafka, mongodb, opensearch and elasticsearch.

2 Operating Instruction

2.1 Operating Environment

JIRA DINGDING plugin (URANUS Sync) supports JIRA (8.0.0) or later.

2.2 Plugin Installation

2.2.1 Prepare for JIRA Plugin Installation

Prepare the downloaded URANUS Sync plug-in package, click the button on the upper right corner of the main system interface to bring up the pop-up menu as shown in Figure 2.2.1.1.

Open

Click “Manage Application” to enter the application management page as shown in Figure 2.2.1.2. At this time, a second password confirmation pop-up will appear, please enter the password of the currently logged-in JIRA account to proceed to the next step.

Open

Click “Manage Application” on the left menu bar to enter the plugin installation procedure.

2.2.2 Sync Configuration

After the plugin is installed, you can see the URANUS Sync plugin in the upper column of the JIRA product. Hover your mouse over URANUS Sync and the Data Sync option will appear, click Data Sync into the Data Sync configuration page.

3 Functions

3.1 Data Source Management

Data source management is divided into two parts:

Data source: configuration for connecting products to obtain data.

Transfer object: map the obtained data into a custom field and synchronize the data with a custom mapping relationship.

3.1.1 Data Source

Connection data that provides data for synchronization and obtains the relevant data through the configuration of the data source.

3.1.1.1 Add a new data source

To create a new data source, click the New Data Source button on the Data Sources page to add a new data source.

3.1.1.1.1 Add a new JIRA data source

1）Fill in the name of the data source.

2）Fill in the description of the data source.

3）Select the data source type JIRA data source.

4）Fill in the data source address (the basic URL of the JIRA system).

5）Select the data source connection method. There are two types of connection methods: one for user name and password access and one for personal token access.

6）Click the Confirm button to save the JIRA data source.

3.1.1.1.2 Add a new ROCKETMQ data source

1）Fill in the data source name.

2）Fill in the description of the data source.

3）Select the data source type ROCKETMQ data source.

4）Fill in the IP address of the data source.

5) Fill in the port number of the data source.

6) Fill in the ROCKETMQ subject.

7）Select the data source user name and password connection method.

8）Click the Confirm button to save the ROCKETMQ data source.

3.1.1.1.3 Add a new RABBITMQ data source

1）Fill in the name of the data source.

2）Fill in the description of the data source.

3）Select the type of data source, RABBITMQ data source.

4）Fill in the IP address of the data source.

5) Fill in the port number of the data source.

6) Fill in the path to the RABBITMQ virtual host.

7）Select the data source user name and password connection method.

8）Click the Confirm button to save the RABBITMQ data source.

3.1.1.1.4 Add a new KAFKA data source

1）Fill in the name of the data source.

2）Fill in the description of the data source.

3）Select the type of data source, KAFKA data source.

4）Fill in the IP address of the data source.

5) Fill in the port number of the data source.

6) Fill in the KAFKA subject.

7）Select the data source user name and password connection method.

8）Click the Confirm button to save the KAFKA data source.

3.1.1.15 Add a new MONGODB data source

1）Fill in the name of the data source.

2）Fill in the description of the data source.

3）Select the data source type MONGODB data source.

4）Fill in the IP address of the data source.

5) Fill in the port number of the data source.

6) Fill in the data source database name.

7） Select the data source user name and password connection method.

8） Click the confirmation button to save the MONGODB data source.

3.1.1.1.6 Add SEARCH data source

SEARCH datasource contains opensearch datasource and elasticsearch datasource.

1）Fill in the name of the data source.

2）Fill in the description of the data source.

3）Select the type of data source: SEARCH data source.

4）Fill in the IP address of the data source.

5) Fill in the port number of the data source.

6） Fill in the number of index slices of the data source.

7） Fill in the number of copies of the data source index.

8） Select the data source user name and password connection method.

9） Click the confirmation button to save the SEARCH data source.

3.1.1.2 Modify a data source

If you want to modify the information of the new data source, you can click the Modify button of the data source to modify it.

1）Click Modify to bring up the Modify Popup Box to modify the data source information.

2）After modifying the information about the data source, click the Confirm button to complete this modification.

3.1.1.3 Delete a data source

If you want to delete a data source, click the corresponding Delete button to delete the data source.

If the data source is being used by the object, a message will be displayed when deleting the data source, and the data source cannot be deleted.

1) Delete the data source by clicking the Delete button of the data source.

2) Click to confirm deletion of the data source

3) The data source cannot be deleted when it is used.

3.1.2 Transfer Objects

Relationally map the data obtained from the data source.

3.1.2.1 Add a New Transfer Object

Create a new transfer object and click the Add Transfer Object button on the Transfer Objects page to add a new transfer object.

1) Click the Add Transfer Object button

2) Pop up the interface of adding new transmission object

Click New Column Properties, fill in the name of the column to be added and the description of the column, choose whether the column name is unique or not (there will be more unique values to distinguish whether to add or update), when synchronization will be based on the name of the column to find out whether there is a value that matches the name of the column, and then go to synchronize the data.

Click the Save button to save the column name.

3) When the column mapping is completed, click the Save button to save it.

4) After clicking Save

1》Fill in the transmission name

2》Fill in the description of the transmission

3》Select the data source

• When the data source is JIRA data source, select Bound Items, then the transfer object will be synchronized with the selected items.

• When the data source is SEARCH data source, select Index/New Index, then the transfer object will be synchronized with the information under the selected index.

• When the data source is a MONGODB data source, select Bind Database Table, then the transfer object will be synchronized with the selected database table.

• When the data source is a RABBITMQ data source, fill in the queue name, then the transfer object will be synchronized with the queue name filled in.

• When the data source is selected as ROCKETMQ/KAFKA data source, fill in the group name, then this transfer object will be synchronized with the selected group.

4》Click the Confirm button to save the transfer object.

5) When the data source for the JIRA data source, SEARCH data source (select non-new index), MONGODB data source also need to bind the product fields to form mapping relationships.

6) Click the Unbound button in Bound Fields to enter the field binding page.

1》When entering the field binding page, the unique field will be bound by default.

2》Bind the new column information to the product field.

3》Click on the default binding field, the system will bind the two fields with the same name.

4》Click Status Binding Relationship to clear the mapping relationship of all fields (except unique field mapping).

5》Click the Delete button on the right to delete the column mapping relationship.

6》Click Save to save the field mapping configuration.

7) The transfer object is added successfully, the status is displayed successfully, and the field binding is displayed: Bound/Not required.

3.1.2.2 Modify Transferred Objects

Modify the transfer object column name and bound data source information by clicking the Modify button corresponding to the transfer object on the Transfer Objects page.

If you want to modify the mapping relationship of a field, click the Bind Field button corresponding to the transport object to modify the mapping relationship of the field.

3.1.2.3 Delete Transferred Objects

If you want to delete a transfer object, click the corresponding Delete button to delete the transfer object.

If the transport object is being used by the transport management or API configuration, a message will be displayed when deleting and the transport object cannot be deleted.

1) Click the Delete button for the transferring object.

2) Click to confirm the deletion of the transferring object.

3) When there is an associated item, deleting the transfer object reports an error, and you need to delete the used task before deleting the transfer object.

3.2 Extend Data Management

Issue extension custom fields, support for issue definition and display of various types of fields.

Extended data management is divided into 3 parts:

1) Form management: add, edit, modify and delete issue custom fields.

2) Data management : issue custom field values for new editing modification delete.

3) View Management: Manage the view interface of the customized fields and control whether the customized fields are displayed in the issue view interface and data management interface.

3.2.1 Form Management

Define issue custom expansion fields according to the project; edit, modify, delete and synchronize the custom fields.

3.2.1.1 Add extended entity objects

1) Click New Extended Entity on the form management screen to add a new extension to an object with customized fields.

2) New Entity Object

Fill in the name of the entity object, select the item you want to extend the field, and click Confirm to generate the entity object.

A project can only bind one entity object, when binding to an existing project will give relevant tips.

3）Click the Edit button to add a new field to the extended field

4) In the Custom Fields Extension page, the system has generated two default fields：

Id and issue_key

Click New Column Properties to enter New Custom Field

5) In the new column attribute interface, fill in the extended field information.

Column name: the name of the custom extended field (only letters and underscores)

Column Type: the type of the customized extended field

Allowed to be empty: whether the extension field is empty or not

Primary Key: whether or not it is the primary key

Column length: the length of the extension field

Default value: if there is a default value, fill in the default value.

Click Confirm to complete column editing.

6) After the column editing is completed, the status of the new column is to be added, at this time has not been formally synchronized to the database.

Click the Undo button under Operation to delete the new class.

Click Save Synchronization to Database to synchronize the new column to the database.

3.2.1.2 Edit an extended entity object

Click the Edit button to modify the custom fields of the extended entity object, delete useless extended fields, and then add a new extended object.

Click Save Sync to Database to update the custom extension fields.

3.2.1.3 Modify the extended entity object name

Click the Modify button to modify the entity object name.

3.2.1.4 Delete extended entity objects

Click the Delete button to delete the extended entity object.

3.2.2 Data Management

Manage the extended custom field values, and update and modify the custom field values for each issue.

3.2.2.1 Add an issue extended field

In the form management, select the project you want to extend, click the Add Data button to add an extension field, select the issue you want, if the issue does not exist in the project, you cannot add it.

3.2.2.2 Edit extended field values

Click the Edit button to edit the extended field value.

3.2.2.3 Delete extension field

Click Delete to delete the specified issue extension field.

3.2.3 View Management

Manage the display position of customized fields; 

Whether to display in table or not: whether to display in data management interface (all display in editing interface);

Whether to display in panel: display in issue view interface.

Selecting items for view management in Forms Management.

Click the edit button in the operation to limit the position of the extended field.

View in the issue browser interface.

3.3 Transfer Management

The transfer management is divided into 4 sections:

• Transfer task: configure the synchronization data task.

• Timing task management: configure the synchronization task as a timing task to synchronize the data at regular intervals.

• Transfer Settings: some configurations for synchronization tasks.

• Keyword Binding: display keywords when JIRA synchronization and send back attachments and comments when the target is a JIRA product.

3.3.1 Transfer Tasks

Configure the transfer object as a synchronization task to synchronize the data.

3.3.1.1 Add transfer tasks

Click Add New Transfer Rule on the Transfer Tasks page of the Transfer Manager, and enter the Add New Transfer Rule screen. When the configuration of a transfer task is completed, the task displays：Completed in the status field of the transfer task display screen.

3.3.1.1.1 Add a new JIRA-JIRA transfer task

To enter the Add New Transfer Task, configure 5 steps to complete the JIRA-JIRA configuration.

1）Select the source site and target site：

Select the site whose data source is JIRA data source, and then select the previously created transmission object. After selecting the source and target, click Next (status configuration) to complete the first step of configuration.

2）In the second step, the state of the source workflow and the state of the target workflow need to be bound, and the state needs to be mapped during synchronization.

• Default Binding: click the Default Binding button to bind the source and target fields with the same name.

• New Binding Relationship: select a source state and a target state, click New Binding Relationship to bind the two fields.

• Empty Binding Relationship: empty all the bound fields.

• Prohibit state jump/allow state jump: when the state is turned on, if the state changes when the source state is synchronized, the target state will also change. Conversely, if the source state changes, it will not affect the target state.

• Delete: delete the mapping field of a single binding.

• Click Next (issuFiled Configuration) to complete the second step.

3）In the third step, you need to bind the fields of the source workflow and the fields of the target workflow, and you need to map the fields (the field types should be the same) when synchronizing.

• Default Binding: click the Default Binding button to bind the source and target fields with the same name.

• New Binding Relationship: select a source state and a target state, click New Binding Relationship to bind the two fields.

• Empty Binding Relationship: empty all the bound fields.

• Delete: delete the mapping field of a single binding.

• Configure issue filters: After the fields are configured, if you need to filter the issues in the project, click this button to jump to the next step.

• Next (issueFiled Configuration): After the fields are configured, if there is no need to filter issues in the project, click the button to go to the next step.

4）Click Configure issue filter to enter the fourth step.

• Click Add Filter to bring up the Add Filter page.

• Filter Field: select the issue field.

• Filter Value: fill in the filter value of the field

• Filter conditions: Equal (synchronization can be performed when the value of the filter field of issue is equal to the filter value)

• Delete: delete a single filte.

• Confirm: completes the addition of the filter.

5）The fifth step, synchronize the issue by selecting Synchronization.

• Synchronize all issues: synchronize all filtered issues.

• Add Synchronization Information: select an issue, click the button to add the issue to the data to be synchronized.

• Empty Synchronized Issues: click the button to empty all synchronized issues (issues in synchronization can not be deleted, only the new issues can be deleted).

• Delete: delete a single issue to be synchronized.

• After selecting an issue, click Save to save the synchronization task.

6）Enter the program information configuration interface.

• Fill in the program name

• Fill in the description of the program

• Select synchronization mode: synchronize selected issues (only the selected issue information is synchronized)

• Synchronize all eligible issues (including new issues in future) , synchronize all issues that meet the filter conditions.

3.3.1.1.2 Add a JIRA-Other data source transfer task

To add a new transfer task, you need to configure four steps to complete the configuration of the JIRA-Other data sources transfer task.

1）Select the source and destination sites

• Source site: JIRA source site

• Destination site: Configuration of other data source transmission task (non-JIRA source site)

• Select the corresponding transfer target.

• Click Next (issueField Configuration) to complete the first step of configuration.

2）In the second step, you need to bind the fields of the source workflow and the target field, and map the fields when synchronizing.

• Default Binding: click the Default Binding button to bind the source and target states with the same name.

• New Binding Relationship: select a source state and a target state, click New Binding Relationship to bind the two fields.

• Empty Binding Relationship: empty all the bound fields.

• Delete: delete the mapping field of a single binding.

• Configure issue filters: After the fields are configured, if you need to filter the issues in the project, click this button to jump to the next step.

• Next (issueFiled Configuration): After the fields are configured, if there is no need to filter issues in the project, click the button to go to the next step.

3）Click Configure Issue Filter to enter the third step.

• Click Add Filter to bring up the Add Filter page.

• Filter Field: select the issue field.

• Filter Value: fill in the filter value of the field.

• Filter conditions: Equal (synchronization can be performed when the value of the filter field of issue is equal to the filter value)

• Delete: delete a single issue to be synchronized.

• Confirm: completes the addition of the filter.

4）The forth step, synchronize the issue by selecting Synchronization.

• Synchronize all issues: synchronize all filtered issues.

• Add Synchronization Information: select an issue, click the button to add the issue to the data to be synchronized.

• Empty Synchronized Issues: click the button to empty all synchronized issues (issues in synchronization can not be deleted, only the new issues can be deleted).

• Delete: delete a single issue to be synchronized.

• After selecting an issue, click Save to save the synchronization task.

5）Enter the program information configuration interface.

• Fill in the program name

• Fill in the description of the program

• Select synchronization mode: synchronize selected issues (only the selected issue information is synchronized)

• Synchronize all eligible issues (including new issues in future) , synchronize all issues that meet the filter conditions.

3.3.1.1.3 Add Non-JIRA data source - Non-JIRA data source

To add a new transfer task, you need to configure two steps to complete the configuration of the JIRA-Other Data Sources transfer task.

1）Select the source and destination sites.

• Source site: non-JIRA source site

• Destination site: non-JIRA source site

• Select the corresponding transfer target.

• Click Next (issueField Configuration) to complete the first step of configuration.

2）To enter the second step, you need to select the source and target transport object fields, and map the fields for synchronization.

• Default Binding: click the Default Binding button to bind the source and target states with the same name.

• New Binding Relationship: select a source state and a target state, click New Binding Relationship to bind the two fields.

• Empty Binding Relationship: empty all the bound fields.

• Delete: delete the mapping field of a single binding.

• Next (Save Synchronization Configuration): After the fields are configured, click this button to enter the Save Configuration interface.

3）Enter the program information configuration interface.

• Fill in the program name

• Fill in the description of the program

• Click the Confirm button to save the synchronization configuration

3.3.1.2 Modify the transfer task

In the operation column of the transfer task screen, click Modify to modify the synchronization configuration. When the configuration of the transfer task is not completed, click Continue to continue configuring the transfer task.

3.3.1.3 Execute the transfer task

When the configuration of the transfer task is complete, click Execute to execute this configured synchronization task (the transfer task status must be completed to be executed).

3.3.1.4 Delete the transfer task

A transfer task can be deleted by clicking the Delete button of the transfer task.

3.3.1.5 Field display

When the transfer task is JIRA synchronized to JIRA, when any party is the JIRA of this product, the field display button can be seen on the display screen, clicking on the field display, you can configure another synchronization source's fields to be displayed on the JIRA of this product.

Configuration Fields Display

Fields: JIRA fields on the other end

Displayed Fields: Fields that are displayed in the JIRA of this product.

Select the fields you want to display to the JIRA of this product, when the data is synchronized, the synchronized issue fields will be displayed on the issue view interface of this product.

This section of the issue field browsing interface display.

Notify button: If the user turns on the mail function, an email will be sent to the agent and reporter of issue at the other end.

3.3.2 Timed Task Management

Click Timed Tasks Management on the Transfer Management page to enter the Timed Tasks display page.

In this section, you can configure the timed tasks for synchronized tasks.

3.3.2.1 Add a New Timed Task

Click New Timed Task to enter the timed task configuration interface.

Task Name: Fill in the name of the task to run the timed task.

Task Description: Fill in the task description of the timed task.

Transfer Rule: select the transfer task you want to run regularly.

Execution Rules: select the cron expression for the running rules of the timed task, and you can configure the year, month, day, hour, minute and second (the minimum execution interval of the JIRA timed task is one minute).

Periodicity: Execute within the specified time period.

Specify: to execute within a specified time.

Start: from the specified time, how long the interval between executions

3.3.2.2 Modify Timed Tasks

Modify this synchronization task by clicking Modify in the Timed Tasks and operation column.

3.3.2.3 Execute Timed Tasks

Perform the synchronization task once by clicking the Execute action in the Timed Tasks and operation column.

3.3.2.4 Start Timed Task

Start the timed synchronization task by clicking Start in the Timed Tasks, operation column.

When the task is started, if you need to stop the timed task, click Stop to stop the timed synchronization task.

3.3.2.5 Delete Timed Task

This timed synchronization task can be deleted by clicking the Delete button in the Timed Tasks and operation column.

3.3.3 Transmission Settings

Some configurations that may be required for the transmission task:

1）Real-time update: when the source data to be synchronized is this JIRA product, turn on this function to complete real-time synchronization.

2）Attachment temporary storage path: when the synchronization task contains attachments, need to specify the attachment directory. The directory needs access, write and delete permissions.

3.3.4 Keyword Bind

When a JIRA synchronization task needs to display the issue from which the synchronization is coming, it can select the field, and after successful configuration, the data synchronized by the synchronization task will write the issueKey of the synchronization to the current issue.

Transfer task name: Select the transfer task

• Synchronize source issue keyword binding fields: select a text custom field for the source issue, and the target issueKey will be displayed in the execute field of the source issue view interface.

• Synchronize target issue keyword binding field: select a text custom field of the target issue, and the source issue key will be displayed in the execute field of the target issue view interface.

• Specify the state to return attachments and comments: if the target issue is a JIRA product, select the specified state, and when attachments or comments are added to the target issue in the specified state, the new attachments or comments will be synchronized to the source issue.

Click the Save button to complete the keyword binding.

3.4 API

The API is divided into 2 sections:

API Configuration: Configure external access API

WebHook: provides a real-time updating interface for synchronization. When the synchronized source data is not in this product, using this interface can realize real-time updating of data.

3.4.1 API configuration

Configure the API according to the data source and transfer object to provide external access to the information in the data source.

3.4.1.1 Create API configuration

Under API Configuration, click “Add API Rule Button” to enter the API Configuration Generation interface.

Select the transport object that needs API access, and if the data source of the transport object belongs to the JIRA type, you can also add filter conditions to filter the limited issue request interface.

Click Save

Fill in the API Configuration Name

Fill in the API configuration description

Click Confirm to create the API Configuration is complete

3.4.1.2 Modify the API configuration

Click the Modify button in the API Configuration to modify the API configuration.

3.4.1.3 Access the creation API

In the column of access format in the API configuration display list, there is a button to view access API, and click access API to pop up the access API mode page.

1）Access the basic information POST method, the access path is as shown in the figure.

http://192.168.0.40:8080/plugins/servlet/third/rest/API/getInfo

Access body information

{

"page":1,

"APIId":1

}

Page data is displayed as 1 page of 1,000 data items, and APIId represents the API access configuration information.

Return data structure presentation.

2）If the data source is a JIRA data source and the attachment field is bound in the API transfer object, the attachment can be downloaded according to the attachment parameter carried in the API for viewing details, as shown in the following figure.

3）If the data source is a JIRA data source, can also use the API update interface to update the issue.

3.4.1.4 Delete API configuration

Click the Delete button to delete the API configuration.

3.4.2 WebHook

Provide webHook interface, when it is enabled, it will use the specified API to synchronize the update.

To enable webHook, turn on the Webhook switch.

Synchronized data update operations：

Request Webhook Url, this method is get method, the request parameter is the issueKey that needs to be synchronized, and the url of the synchronization configuration (the base url of the issueKey's JIRA).

3.5 Notification Management

Notification management: during the synchronization process, send emails to the operator and reporter of the synchronized target issue to remind the related personnel to handle the issue.

The left side is the optional scalar for sending emails. When there are relevant variables in the email title/content, the email will be automatically replaced with the relevant information of the issue.

The right side is the configuration of the email:

Whether to open the mail: when it is closed, there is no mail sending function, and when it is opened, the send mail button will appear in the issue operation interface;

Apply all configurations: when turned on, all synchronizations can send emails;

Select transmission configuration: select the specified transmission configuration to have the function of sending emails;

Select mail sender: select the reporter and the operator;

Email title: specify the email title;

Email content: specify the content of the email.

Click Confirm to save the right-click configuration

3.6 Log Management

Log management is divided into 4 sections:

Transfer logs: logs generated when synchronizing data

API access logs: logs generated by accessing the API configured by the API

System operation log: logs generated by user operations

Log configuration: whether to delete the log configuration

3.6.1 Transfer Log

View the logs generated by synchronizing data by clicking Transfer Log under Log Management.

Check whether the synchronization was successful in the transfer log.

1）View logs: Click the query conditions, you can query the transmission logs according to the log name, log status and specific time.

2） Delete the log operation

3）Download Transfer Log

3.6.2 API Access Log

Click API Access Log under Log Management to view the API use in the API Access Log.

1）View API Access Logs: Click the query conditions, you can query according to the log name, log status and specific time.

2） Delete the log operation

3.6.3 System Operation Log

Click System Operation Log under Log Management to view logs generated by user operations.

1）Query logs

Click on the query condition: Click the query conditions, you can query logs according to the log name, log status and specific time.

2）Delete logs

3.6.4 Log Configuration

Configure the log deletion policy under the log configuration of log management.

Automatic deletion of logs: Off: Turn off scheduled deletion of logs.

Select Delete Log Type: select the log type that needs to be deleted regularly.

Automatic deletion condition: days, calculated according to days; Month, calculated on a monthly basis; Year, calculated by year.

Time: how many days/months/years are accumulated to calculate.