Automation Anywhere A2019でAPI経由のBotインポート/エクスポートを行う

A2019.13以降、BLM APIが実装され、API経由でBotのインポート/エクスポートができるようになりました。また、Community Edition (CE)はA2019.13がスキップされたため、2020年7月初旬のA2019.14へのアップデート以降、BLM APIが使えるようになっています。フリートライアル (FT)でも利用できるようになっているため、UI上はエクスポートコマンドが利用できなかったCE/FTでもインポート/エクスポートができるのではないかと期待が持てます。

[Enterprise A2019.13 Release Notes](https://docs.automationanywhere.com/bundle/enterprise-v2019/page/enterprise-cloud/topics/release-notes/cloud-release-a2019-13.html)より引用:
>**Export and import files using BLM APIs**
>Use the Bot Lifecycle Management (BLM) export and import APIs to move bots from one environment to another based on your organization's automation requirements.
>
>You can export bots with dependent files and command packages from the public workspace of one Enterprise Control Room and import them to a private workspace in another Enterprise Control Room, and check them into a public workspace. To export and import bots, you must have the Export bots, Import bots, View and Manage packages, and Check in and Check out permissions to the necessary folders and have the Bot Creator license.
>
>[Bot Lifecycle Management API](https://docs.automationanywhere.com/bundle/enterprise-v2019/page/enterprise-cloud/topics/release-notes/cloud-release-a2019-13.html)

そこで、さっそく試してみました！

# Bot のエクスポート (CE/FT共に不可)

https://community.cloud.automationanywhere.digital/swagger/
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/479715/8861000a-9c7c-3e0f-eeec-801187b794ec.png)
この中では、**①Authentication API、②Bot Execution Orchestrator API、③BLM API**の順に3つのAPIを使います。

1. まず、①Authentication APIのページを開きます。<br/>`https://community.cloud.automationanywhere.digital/swagger/ui/?url=/swagger/api/v1/auth-api-supported.yaml`<br/>![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/479715/0d3f1dfc-3acd-aa53-45fd-431dd5740133.png)<br/>
開いた後のページ内でSchemesでHTTPSを選択します。
2. `/authentication` (ユーザーに権限を与える)メソッドのセクションを開いて、「Try it out」ボタンを押します。<br/>![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/479715/e3500adf-e5ce-1a68-92bb-2baa4809c6c7.png)<br/>body部分が編集できるようになるので、apiKeyを消して、username、passwordに適切なユーザー名とパスワードを指定して、「Execute」ボタンを押します。<br/>![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/479715/e8541e7c-2d93-6cde-fb7c-87f7d4b79081.png)
3. 正常に実行されると、Response部分にapiKeyが返ります。下記の図のtoken (ハイライト部分) をクリップボードにコピーしておきます。このtoken (apiKey)は同じユーザーでControl Roomにサインインすると期限が切れてしまうので注意してください。<br/>![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/479715/61e4af19-eb87-d870-b833-f3c8334ad69c.png)
4. 次に、②Bot Execution Orchestrator APIのページを開きます。<br/>`https://community.cloud.automationanywhere.digital/swagger/ui/?url=/swagger/api/v2/bot-execution-orchestrator-api-supported.yaml`<br/>開いた後のページ内でSchemesにHTTPSを選択した後、「Authorize」ボタンを押して先ほどのtokenで認証を行います。<br/>
5. `/repository/file/list` (リポジトリ内のファイル検索)メソッドのセクションを開いて「Try it out」ボタンを押します。<br/>
6. body部分が編集できるようになるので、以下の値を入れて「Execute」ボタンを押します。(MessageBoxというBotのエクスポートを行う)
>```
>{
>  "filter": {
>    "operator": "eq",
>    "value": "MessageBox",
>    "field": "name"
>  }
>}
>```
>すると、戻り値として以下の値が返ります。ここではMessageBoxのfileId=31であることがわかります。
>
>```
>{
>  "page": {
>    "offset": 0,
>    "total": 11,
>    "totalFilter": 1
>  },
>  "list": [
>    {
>      "id": "31",
>      "parentId": "9",
>      "name": "MessageBox",
>      "permission": {
>        "delete": true,
>        "download": true,
>        "execute": false,
>        "upload": true,
>        "run": true,
>        "publishBotstore": false
>      },
>      "lastModified": "2020-07-11T15:15:05.009218600Z",
>      "lastModifiedBy": "2",
>      "path": "Automation Anywhere\\Bots\\MessageBox",
>      "directory": false,
>      "size": "0",
>      "locked": false
>    }
>  ]
>}
>```

7. 次に、③BLM APIのページを開きます。<br/>`https://community.cloud.automationanywhere.digital/swagger/ui/?url=/swagger/api/v2/blm-api.yaml`<br/>開いた後のページ内でSchemesにHTTPSを選択した後、「Authorize」ボタンを押して先ほどのtokenで認証を行います。<br/>![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/479715/31aa492a-077e-a19d-7f3b-16f83ee56038.png)
8.  `/v2/blm/export` (リポジトリのボットをアーカイブファイルにエクスポートする)メソッドのセクションを開いて、「Try it out」ボタンを押します。<br/>
9. body部分が編集できるようになるので、以下の値を入れて「Execute」ボタンを押します。
>```
>{
>  "name": "MessageBox.zip",
>  "fileIds": [31],
>  "includePackages": true,
>  "archivePassword": ""
>}
>```

しかし、残念ながらExport実行を行うと以下の403 Errorが出て、権限がないといわれてしまいました。残念ながらAPI経由でエクスポートはできませんでした。

```
{
  "code": "blm.insufficient.permission.repositorymanager.export",
  "correctiveAction": "To continue, please contact your system administrator.",
  "details": "",
  "message": "You do not have required permissions"
}
```

フリートライアルでも同じでした...
https://trial.cloud.automationanywhere.digital/swagger/

### 商用版で実行すると... 
商用版で同様のステップを実行すると、Control Room上にダウンロードファイルのZIPが用意されます。準備が完了したかどうかを `/v2/blm/status/{requestId}`メソッドで監視して、用意がされたタイミングで `/v2/blm/downoad/{downloadFileId}`メソッドでダウンロードが必要とのことで、コマンドラインツールでファイルをローカルPCにまでダウンロードするには追加の作り込みが必要そうです。今回はパスしました。

# Botのインポート (CE可、FT不可)
CEにはインポートの機能が付きましたが、APIでも実施できることを確認しました。FTは結論から言うと権限がなくダメでした。

初期の状態:
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/479715/e14481f9-13e1-010b-f7c7-9ba18cc17bfd.png)


https://community.cloud.automationanywhere.digital/swagger/
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/479715/8861000a-9c7c-3e0f-eeec-801187b794ec.png)
この中では、**①Authentication API、②BLM API**の順に2つのAPIを使います。

1. まず、①Authentication APIのページを開きます。<br/>`https://community.cloud.automationanywhere.digital/swagger/ui/?url=/swagger/api/v1/auth-api-supported.yaml`<br/>![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/479715/0d3f1dfc-3acd-aa53-45fd-431dd5740133.png)<br/>
開いた後のページ内でSchemesでHTTPSを選択します。
2. `/authentication` (ユーザーに権限を与える)メソッドのセクションを開いて、「Try it out」ボタンを押します。<br/>![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/479715/e3500adf-e5ce-1a68-92bb-2baa4809c6c7.png)<br/>body部分が編集できるようになるので、apiKeyを消して、username、passwordに適切なユーザー名とパスワードを指定して、「Execute」ボタンを押します。<br/>![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/479715/e8541e7c-2d93-6cde-fb7c-87f7d4b79081.png)
3. 正常に実行されると、Response部分にapiKeyが返ります。下記の図のtoken (ハイライト部分) をクリップボードにコピーしておきます。このtoken (apiKey)は同じユーザーでControl Roomにサインインすると期限が切れてしまうので注意してください。<br/>![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/479715/61e4af19-eb87-d870-b833-f3c8334ad69c.png)
4. 次に、②BLM APIのページを開きます。<br/>`https://community.cloud.automationanywhere.digital/swagger/ui/?url=/swagger/api/v2/blm-api.yaml`<br/>開いた後のページ内でSchemesにHTTPSを選択した後、「Authorize」ボタンを押して先ほどのtokenで認証を行います。<br/>![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/479715/31aa492a-077e-a19d-7f3b-16f83ee56038.png)
5.  `/v2/blm/import` (アーカイブファイルからリポジトリにボットをインポートする)メソッドのセクションを開いて、「Try it out」ボタンを押します。<br/>![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/479715/418b20fd-9cfc-3574-51a3-cb64c2006626.png)
6. fileはファイル選択ダイアログボックスで選択、publicWorkspaceはfalseを選択して「Execute」ボタンを押します。<br/>![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/479715/1a2b30b9-0ed3-1568-2cef-07d48ae7bd64.png)<br/>インポートするファイルは[SalesforceContactEntryAutomationAnywhere.zip](https://botcenter.automationanywhere.com/Salesforce+contact+entry+Automation+Anywhere.zip)をあらかじめダウンロードしておいてください。


成功すると、以下のようなメールが届きます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/479715/53154805-fa5e-d01d-949b-3130178cf829.png)

Community Editionに再ログインして確認すると、以下のようにフォルダーとBotファイルができているのがわかります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/479715/c86f1995-c65a-e65a-50c6-22cae7e11a06.png)


curlおよびjq-win64で作成したコマンドラインで表現すると以下の通りです[^1]。アーカイブファイル (.zip)は、.cmdファイルと同じディレクトリに置いておきます。おそらくカレントディレクトリにおいておけばOKです。

```:ImportToCommunityEdition.cmd
@SET username=%~1
@SET password=%~2
@SET filename=%~3
@curl -s -X POST "https://community.cloud.automationanywhere.digital/v1/authentication" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"username\": \"%username%\", \"password\": \"%password%\"}" | jq-win64 -r .token > %TMP%\tmp.txt
@SET /p token=<%TMP%\tmp.txt
@DEL %TMP%\tmp.txt
@curl -s -X POST "https://community.cloud.automationanywhere.digital/v2/blm/import" -H "accept: application/json" -H "X-Authorization: %token%" -H "Content-Type: multipart/form-data" -F "upload=@%filename%;type=application/zip" -F "actionIfExisting=SKIP" -F "publicWorkspace=false"
@pause
```

コマンドラインから以下のように引数を付けて呼び出します。
`ImportToCommunityEdition.cmd (username) (password) (filename)`

メモ

* コマンドライン引数に`%~1`などの「チルダ」を付けると、引数全体が引用符で囲われている場合は引用符が削除されたものを参照します。
* Swagger UIで生成されるcurlコマンドにサイレントオプション`-s`を付けています。
* jq-win64にはcurlコマンドからパイプでJSONを渡します。`-r`オプションを付けると外側で囲っている引用符が削除されたものを返します。
* コマンドプロンプトでは、標準出力 (stdout)の内容を変数に直接代入できないため、一旦一時ファイル ("`%TMP%\tmp.txt`")に結果を出力して、そのファイルの内容を次の行の`SET /p`コマンドで変数に代入します。

ImportToCommunityEditionを実行すると、ファイルサイズによっては少し時間がかかり、コマンドラインからは無反応になります。しばらくすると正常終了すると`requestID`のGUIDが表示されます。

### フリートライアルではインポート権限がない...!!
Community Editionと同じことをフリートライアルでもURLを変えて実行してみました。
https://trial.cloud.automationanywhere.digital/swagger/

しかし、残念ながらImport実行を行うと以下の403 Errorが出て、権限がないといわれてしまいました。残念ながらAPI経由でもインポートはできませんでした。

```
{
  "code": "blm.insufficient.permission.import",
  "correctiveAction": "To continue, please contact your system administrator.",
  "details": "",
  "message": "You do not have required permissions"
}
```

# まとめ
結局、Automation AnywhereではユーザーのRBAC (ロールベースアクセス制御)によってUIやAPIが一括で管理されているため、UIで表示されていないものはAPIでも実行できないという結果になりました。まとめると以下の通りです。残念。。。将来的にCE/FTでもインポート/エクスポートができるようになってほしいです。

||商用版[^2]|CE|FT|
|:--|:--:|:--:|:--:|
|インポート|○|○|×|
|エクスポート|○|×|×|



[^1]: 中身の詳しい解説は『[Automation Anywhere A2019でコマンドラインからBotを実行する](https://qiita.com/RPAbot/items/8c313f137ff089a0014d)』をご覧ください。
[^2]: ユーザーに適切な権限が振られていることが前提