diff --git a/docs/best-practices.md b/docs/best-practices.md index ce0ffcca8f3d3572e2c005db26a096aec6606c6c..32cd70d194d39771be2c2508b89aff179144a3e9 100644 --- a/docs/best-practices.md +++ b/docs/best-practices.md @@ -1,32 +1,6 @@ -# Best Practices +# Best Practices And Recommendations Here are some recommended best practices for designing integrations in IICS. -## Working In a Shared Environment - -UW-Madison operates under a single shared IICS org for each environment (test and production). -This means that you might see other objects in IICS, such as projects, connections, and schedules, that belong to other areas of the university. - -### Use User Groups to Control Access - -When you create a new project, make sure you edit the permissions to limit who can view and change the assets within the project. -**If no permissions are configured on a project or the assets within it, anybody who has access to IICS will be able to view, change, run, and delete the contents of the project.** -Use the group that was sent when you were granted access to IICS to control who can access the contents of the project. - -1. Right-click on a project folder and click "Permissions..." ![Project right-click menu](./images/right-click-permissions.png) -1. Click "Add" to add bring up the group selection menu. ![Project permissions menu without group](./images/add-group.png) -1. Select the group for your team and click "Add". ![Group selection menu](./images/select-group.png) -1. Click the check boxes for Read, Update, Delete, Execute, and Change Permission. ![Project permissions menu with permissions applied.](./images/apply-permissions.png) -1. Click Save. - -### Namespace Projects With Your Group Name - -Even though you might not have any permissions on a project, you are still able to see that the project exists when exploring all projects. -To help organize the constantly growing list of projects, we recommend that you to prefix your group name before the name of the project: `{group name} - {project name}` - -Example: "DoIT-AIS-Enterprise-Integration - Salesforce Integrations" - -This structure allows you to search your group name in the project explorer to only see a list of your group's projects. -You can create subfolders within a project if further organization/hierarchy is needed. - -Your group name was sent when you were granted access to IICS and you can find the name of your group by editing the permissions for a project. \ No newline at end of file +* [Working In a Shared Environment](best-practices/shared-enviornment.md) +* [Naming Conventions](best-practices/naming.md) \ No newline at end of file diff --git a/docs/best-practices/naming.md b/docs/best-practices/naming.md new file mode 100644 index 0000000000000000000000000000000000000000..9e2cbbee26e0747ac73fce6834ac9b87f97b54b7 --- /dev/null +++ b/docs/best-practices/naming.md @@ -0,0 +1,19 @@ +# Naming Conventions For IICS Artifacts +The following naming conventions are recommended for various IICS assets. These conventions will: +* Help to locate assets quickly when searching for them in IICS web designer. +* Provide an indication what the asset function is based on asset's name. +* Increase the readability when using IICS web designer. + +| IICS Artifact| Naming Convention |Examples | +|:-----------|:-------------|:-------------------------| +| Secure Agent Group |<ul><li>Use logical names for groups</li><li>Use uppercase, and use underscore to separate words</li><li>Use documented abbreviations</li><li>Name structure: `<group_logical_name>`</li></ul> |<ul>`ODMAS`</ul><ul>`DCS`</ul><ul>`BATCH_PROCESSING_AGENT_GROUP`</ul>| +| Secure Agent | <ul> <li>Name Secure Agents using logical names rather than host names</li><li>This way agents can be migrated easily to a different host</li><li>Use lowercase, and use underscore to separate words</li><li>Name structure: `<group>_<agent_logical_name>`</li></ul>|<ul>`ODMAS_test_agent`</ul><ul>`DCS_prod_agent`</ul><ul>`batch_processing_agent`</ul>| +| Connections|<ul><li>Use documented abbreviations and use upper case for abbreviations</li>Use logical names<li>Use underscore to separate words</li><li>Generic name structure: `<ConnectionType>_<logical_name>_<flag(s)>`<ul><li>Database: `<db_type>_<logical_name>_<schema_name>`</li><li>Flat File: `FF_<logical_name>_<folder_name>`</li></ul></li>| <ul>`ORCL_siebel_contact_center`</ul><ul>`FF_salesforce_lookups`</ul><ul>`ODBC_Accounting`</ul>| +| Tasks |<ul><li>Use underscore to separate words</li><li>Include task operation in the name.</li><li>Use consistent naming for different type of tasks</li><li>Name structure: `DSS_<SOURCE>_<TARGET>_<NAME>_(INSERT|UPDATE|DELETE)_<VERSION>`</li></ul> |<ul>`DSS_Salesforce_Workday_Accounts_UPDATE_01`</ul><ul>`DSS_Salesforce_Workday_Accounts_UPDATE_02`</ul><ul>`DSS_Coupa_SAP_Requisition_NA_INSERT`</ul>| +| Mappings | <ul><li>Use underscore to separate words</li><li>Use consistent naming for different type of mappings</li><li>Name structure:<ul><li>Mapping with single source: `M_<SOURCE>_<TARGET>_<NAME>_<VERSION>`</li><li>Mapping with multiple sources: `M_<SOURCE>_<ENTITY>_to_<TARGET>_<NAME>_<VERSION>`</li></ul></li></ul>|<ul>`M_CDI_Accounts_FF_incremental`</ul><ul>`M_CDI_Accounts_Contacts_to_SFDC`</ul>| +| Task Flows | <ul><li>Use underscore to separate words</li><li>Use consistent and readable(mix case) naming</li><li>Name structure: `TF_<NAME>_<VERSION>`</li></ul>|<ul>`TF_CDI_Acount_Contacts_to_SFDC`</ul><ul>`TF_Hierarchy_Change_Processing`</ul>| +| Schedulers | <ul><li>Use underscore to separate words</li><li>Use consistent and readable(mix case) naming</li><li>Name structure: `Schedule_<TIMEZONE>_<Frequency>_<TIME>`</li></ul>|<ul>`Schedule_Five_Minutes`</ul> <ul>`Schedule_PST_Daily_11PM`</ul>| +| Project/Folders | <ul><li>See [Projects Namespace](./shared-enviornment.md)</li><li>Name structure: `{group name} - {project name}`</li></ul>|<ul>`DoIT-AIS-Enterprise-Integration - Salesforce Integrations`</ul>| + +Reference: +* [Informatica Cloud Naming Conventions](https://github.com/jbrazda/Informatica/blob/master/Guides/InformaticaCloud/naming_conventions.md) \ No newline at end of file diff --git a/docs/best-practices/shared-enviornment.md b/docs/best-practices/shared-enviornment.md new file mode 100644 index 0000000000000000000000000000000000000000..cd399e95b5584cb0f6d0d318c89369aaa1819918 --- /dev/null +++ b/docs/best-practices/shared-enviornment.md @@ -0,0 +1,28 @@ +# Working In a Shared Environment + +UW-Madison operates under a single shared IICS org for each environment (test and production). +This means that you might see other objects in IICS, such as projects, connections, and schedules, that belong to other areas of the university. + +## Use User Groups to Control Access + +When you create a new project, make sure you edit the permissions to limit who can view and change the assets within the project. +**If no permissions are configured on a project or the assets within it, anybody who has access to IICS will be able to view, change, run, and delete the contents of the project.** +Use the group that was sent when you were granted access to IICS to control who can access the contents of the project. + +1. Right-click on a project folder and click "Permissions..." ![Project right-click menu](../images/right-click-permissions.png) +1. Click "Add" to add bring up the group selection menu. ![Project permissions menu without group](../images/add-group.png) +1. Select the group for your team and click "Add". ![Group selection menu](../images/select-group.png) +1. Click the check boxes for Read, Update, Delete, Execute, and Change Permission. ![Project permissions menu with permissions applied.](../images/apply-permissions.png) +1. Click Save. + +## Namespace Projects With Your Group Name + +Even though you might not have any permissions on a project, you are still able to see that the project exists when exploring all projects. +To help organize the constantly growing list of projects, we recommend that you to prefix your group name before the name of the project: `{group name} - {project name}` + +Example: "DoIT-AIS-Enterprise-Integration - Salesforce Integrations" + +This structure allows you to search your group name in the project explorer to only see a list of your group's projects. +You can create subfolders within a project if further organization/hierarchy is needed. + +Your group name was sent when you were granted access to IICS and you can find the name of your group by editing the permissions for a project. \ No newline at end of file