Skip to content

Commit dbc992e

Browse files
rweesnerrweesner
authored
Merge pull request #2 from Bertievh/main
Initial documents
2 parents e48017f + 52be9fb commit dbc992e

34 files changed

+4212
-4519
lines changed

‎.github/workflows/build.yml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ name: build
22

33
on:
44
pull_request:
5-
branches: [ main ]
5+
branches: [main]
66

77
jobs:
88
build:
@@ -11,6 +11,6 @@ jobs:
1111
- uses: actions/checkout@v2
1212
- uses: actions/setup-node@v2
1313
with:
14-
node-version: '14'
14+
node-version: "18"
1515
- run: yarn install
1616
- run: yarn build

‎docs/ACSAzureWebserviceOperation.md

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
---
2+
slug: '/'
3+
sidebar_label: 'ACSAzureWebservices Operation'
4+
---
5+
6+
# ACSAzureWebservices Operation
7+
8+
Once the sma.acs.ACSAzureWebservices plugin has been registered with the OpCon system, it will be possible to perform agent and task definitions.
9+
All definitions can only be performed using Solution Manager.
10+
11+
## Defining ACSAzureWebservices connection
12+
13+
The Agent definition is defined by adding a new ACSAzureWebservices Agent definition using Solution Manager.
14+
Items defined in red are required values.
15+
16+
![Defining a Connection](../static/img/azure-ws-agent.png)
17+
18+
1. Open Solution Manager.
19+
2. From the Home page select **Library**
20+
3. From the ***Administration*** Menu select **Agents**.
21+
4. Select **+Add** to add a new agent definition.
22+
5. Fill in the agent details
23+
- Insert a unique name for the connection.
24+
- Select **ACSAzureWebservices** from the **Type** drop-down list.
25+
- Select **ACSAzureWebservices Settings**
26+
- The **Azure URL** field contains a default value ***azure.status.microsoft/en-us/status*** which is used as a heartbeat to check if the Azure environment is available.
27+
6. Save the definition changes.
28+
7. Start the connection by selecting the **Change Communication Status** button and selecting **Enable Full Comm.**.
29+
30+
## Defining tasks
31+
32+
The ACSAzureWebservices Connection supports the following task types:
33+
34+
TaskType | Description
35+
---------------------|------------
36+
GetOAuth2Token | Get an OAuth2 token
37+
GetPatToken | Create a Azure DevOps authentication token using a PAT (Personal Access Token)
38+
RunDevOpsPipeline | Starts an Azure DevOps pipeline and monitors for completion
39+
DownloadBlobStorage | Download a file from Azure Blob Storage
40+
UploadBlobStorage | Upload a file to Azure Blob Storage
41+
42+
Before defining a **RunDevOpsPipeline** task, a **GetPatToken** task must be defined to create the authorization token required by the RunDevOpsPipeline Task. Similarly before defining the **DownloadBlobStorage** or **UploadBlobStorage** tasks a **GetOAuth2Token** must be defines to create the autherization task required by the DownloadBlobStorage and UploadBlobStorage tasks.
43+
44+
The generated authentication tasks (GetPatToken, GetOAuth2Token) store the generated token as schedule instance properties of the schedule. These properties are then available for subsequent tasks in the schedule.
45+
46+
### GetOAuth2Token Task
47+
48+
The GetOAuth2Token task is used to get an OAuth2 token and set it as a schedule instance property so it can be used to provide authentication by subsequent Azure tasks.
49+
50+
![Defining a GetOAuth2Token Master Job](../static/img/azure-ws-getaoauth2token-master-job1.png)
51+
52+
1. Open Solution Manager.
53+
2. From the Home page select **Library**
54+
3. From the ***Administration*** Menu select **Master Jobs**.
55+
4. Select **+Add** to add a new master job definition.
56+
5. Fill in the task details.
57+
- Select the **Schedule** name from the drop-down list.
58+
- In the **Name** field enter a unique name for the task within the schedule.
59+
- Select **ACSAzureWebservices** from the **Job Type** drop-down list.
60+
- Select **GetOAuth2Token** from the **Task Type** drop-down list.
61+
62+
Enter details for Task Type **GetOAuth2Token**.
63+
64+
1. Select the **Task Details** button.
65+
2. In the **Integration** section, enter the information to obtain an authentication token. Items defined in red are required values.
66+
3. In the **Authentication** section, field enter the Url, client, key and resource information. Select the Grant Type and enter a name value pair in the Response Variable section to contain the generated token.
67+
- In the **Url** field enter the information to where to retrieve the url from. The value includes the unique tenant id (i.e. tenant-id/oauth2/token).
68+
- In the **Clientid** field enter the client id created during the Azure Application registration process.
69+
- In the **Key** field enter the key created during the Azure Application registration process.
70+
- In the **Resource** field, enter the storage resource containing the storage account name (i.e. https://storage-account.blob.core.windows.net).
71+
- Select ***client_credentials*** from the drop-down list of the **Grant Type** field.
72+
4. In the **Request** section enter the following information
73+
- Select ***application/x-www-form-urlencoded*** from the **Content** the drop-down list.
74+
75+
![Defining a GetOAuth2Token Master Job](../static/img/azure-ws-getaoauth2token-master-job2.png)
76+
77+
5. In the **Response** section enter the following information
78+
- Select ***application/json*** from the **Content** the drop-down list.
79+
- In the **Response Variable** section, define the variable that will contain the OAuth2 token. The format is name=value where the name part will be the schedule instance property name, the value part is ignored.
80+
81+
### GetPatToken Task
82+
83+
The GetPatToken task is used to set a PAT token as a schedule instance property so it can be used to provide authentication by subsequent Azure DevOps tasks.
84+
85+
![Defining a GetPatToken Master Job](../static/img/azure-ws-getpattoken-master-job.png)
86+
87+
1. Open Solution Manager.
88+
2. From the Home page select **Library**
89+
3. From the ***Administration*** Menu select **Master Jobs**.
90+
4. Select **+Add** to add a new master job definition.
91+
5. Fill in the task details.
92+
- Select the **Schedule** name from the drop-down list.
93+
- In the **Name** field enter a unique name for the task within the schedule.
94+
- Select **ACSAzureWebservices** from the **Job Type** drop-down list.
95+
- Select **GetPatToken** from the **Task Type** drop-down list.
96+
97+
Enter details for Task Type **GetPatToken**.
98+
99+
1. Select the **Task Details** button.
100+
2. In the **Integration Selection** section, select the primary integration which is an ACSAzureWebservices connection previously defined.
101+
3. In the **Authentication** section, enter a PAT (Personal Action Token) retrieved from the Azure DevOps environment (see https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=Windows for information on how to create a PAT).
102+
4. In the **Response Variable** section, define the variable that will contain the PAT token. The format is name=value where the name part will be the schedule instance property name, the value part is ignored.
103+
104+
### RunDevOpsPipeline Task
105+
106+
The RunDevOpsPipeline task is used to start a DevOps pipeline and monitor the started task for completion.
107+
A Job Dependency should be defined on a previous **GetPatToken** task.
108+
109+
![Defining a RunDevOpsPipeline Master Job](../static/img/azure-ws-rundevopspipeline-master-job.png)
110+
111+
1. Open Solution Manager.
112+
2. From the Home page select **Library**
113+
3. From the ***Administration*** Menu select **Master Jobs**.
114+
4. Select **+Add** to add a new master job definition.
115+
5. Fill in the task details.
116+
- Select the **Schedule** name from the drop-down list.
117+
- In the **Name** field enter a unique name for the task within the schedule.
118+
- Select **ACSAzureWebservices** from the **Job Type** drop-down list.
119+
- Select **RunDevOpsPipeline** from the **Task Type** drop-down list.
120+
121+
Enter details for Task Type **RunDevOpsPipeline**. Fields marked in red must be provided.
122+
123+
1. Select the **Task Details** button.
124+
2. In the **Integration Selection** section, select the primary integration which is an ACSAzureWebservices connection previously defined.
125+
3. In the **Job Configuration** section enter the following information
126+
- In the **Azure Url** field enter ***dev.azure.com***.
127+
- In the **Organization** field enter the name of the DevOps Organization.
128+
- In the **Project** field enter the name of the DevOps Project within the DevOps Organization.
129+
- In the **Pipeline Name** field, enter the name of the DevOps pipeline to execute.
130+
4. In the **Request** section enter the following information
131+
- Select the **Content** from the drop-down list.
132+
- In the **Header Attributes** section, add an ***Authorization=name*** where the name portion is the name portion assigned to contain the PAT token in a previous GetPatToken task.
133+
5. In the **Response** section enter the following information
134+
- Select the **Content** from the drop-down list.
135+
- In the **Response Variables** section a variable can be defined to contain data extracted from the returned JSON data. The
136+
extracted data will be stored as a schedule instance property in the schedule making the extracted information available to subsequent tasks.
137+
The format of the field definition is variable-name=jsonpath where
138+
- variable-name is the name of the variable that will be created as a schedule instance property.
139+
- jsonpath is the attribute value to extract from the returned JSON data using JPath notation
140+
(i.e. ***$.id*** indicates extract the value of the first ***id*** attribute in the returned JSON,
141+
***$.[0].id*** indicates extract the value of the first ***id*** attribute from the first record in the returned JSONArray).
142+
143+
### DownloadStorageBlob Task
144+
145+
The UploadBlobStorage task is upload a file to Azure BlobStorage.
146+
A Job Dependency should be defined on a previous **GetOAuth2Token** task.
147+
148+
![Defining a DownloadBlobStorage Master Job](../static/img/azure-ws-downloadblobstorage-master-job.png)
149+
150+
1. Open Solution Manager.
151+
2. From the Home page select **Library**
152+
3. From the ***Administration*** Menu select **Master Jobs**.
153+
4. Select **+Add** to add a new master job definition.
154+
5. Fill in the task details.
155+
- Select the **Schedule** name from the drop-down list.
156+
- In the **Name** field enter a unique name for the task within the schedule.
157+
- Select **ACSAzureWebservices** from the **Job Type** drop-down list.
158+
- Select **DownloadBlobStorage** from the **Task Type** drop-down list.
159+
160+
Enter details for Task Type **UploadBlobStorage**. Fields marked in red must be provided.
161+
162+
1. Select the **Task Details** button.
163+
2. In the **Integration Selection** section, select the primary integration which is an ACSAzureWebservices connection previously defined.
164+
3. In the **DownloadAzureBlob** section enter the following information
165+
- In the **Storage Account** field enter the name of the storage account.
166+
- In the **Path** field enter the path of the file to be downloaded from the storage area. The value consists of
167+
the container name and the filename (i.e. container/filename).
168+
- In the **Filename** field enter the name of the file to create. Please note that the file location is relative to the system where the plugin is installed.
169+
4. In the **Request** section enter the following information
170+
- Select the **Content** from the drop-down list.
171+
- In the **Header Attributes** section, add an ***Authorization=name*** where the name portion is the name portion assigned to contain the OAuth2 token in a previous GetOAuth2Token task.
172+
173+
### UploadStorageBlob Task
174+
175+
The UploadBlobStorage task is upload a file to Azure BlobStorage.
176+
A Job Dependency should be defined on a previous **GetOAuth2Token** task.
177+
178+
![Defining a UploadBlobStorage Master Job](../static/img/azure-ws-uploadblobstorage-master-job.png)
179+
180+
1. Open Solution Manager.
181+
2. From the Home page select **Library**
182+
3. From the ***Administration*** Menu select **Master Jobs**.
183+
4. Select **+Add** to add a new master job definition.
184+
5. Fill in the task details.
185+
- Select the **Schedule** name from the drop-down list.
186+
- In the **Name** field enter a unique name for the task within the schedule.
187+
- Select **ACSAzureWebservices** from the **Job Type** drop-down list.
188+
- Select **UploadBlobStorage** from the **Task Type** drop-down list.
189+
190+
Enter details for Task Type **UploadBlobStorage**. Fields marked in red must be provided.
191+
192+
1. Select the **Task Details** button.
193+
2. In the **Integration Selection** section, select the primary integration which is an ACSAzureWebservices connection previously defined.
194+
3. In the **UploadAzureBlob** section enter the following information
195+
- In the **Storage Account** field enter the name of the storage account.
196+
- In the **Path** field enter the path where the file must be placed within the storage area. The value consists of
197+
the container name and the filename (i.e. container/filename).
198+
- In the **Filename** field enter the name of the file to upload. Please note that the file location is relative to the system where the plugin is installed.
199+
4. In the **Request** section enter the following information
200+
- Select the **Content** from the drop-down list.
201+
- In the **Header Attributes** section, add an ***Authorization=name*** where the name portion is the name portion assigned to contain the OAuth2 token in a previous GetOAuth2Token task.

0 commit comments

Comments
 (0)