Python- en HCL-scripting in Robots

De Robots-app biedt native, cloudgebaseerde scripting die u kunt gebruiken voor gegevensanalyse of voor het automatiseren van delen van de Diligent One-workflow van uw organisatie. Robots-scripting combineert de volledige kracht van Python en al zijn ondersteunde bibliotheken met HighBond Command Language (HCL), onze aangepaste Python-bibliotheek voor domeingerichte gegevensanalyse en Diligent One-automatisering.

Robots blijft ondersteuning bieden voor gegevensanalyse en gegevensautomatisering met behulp van ACLScript en scripts die zijn geüpload vanuit Analytics. Zo profiteert u van eventuele bestaande investeringen in ACL (Audit Command Language) en alle mogelijkheden die worden geboden door Python, een programmeertaal die de industriestandaard is, en HCL.

Drie soorten robots

De Robots-app bevat drie soorten robots. De verschillende robottypes ondersteunen verschillende scriptscenario's, hoewel ze in veel opzichten vergelijkbaar zijn:

• ACL-robot Ondersteunt grootschalige gegevensanalyse met scripts die u uploadt vanuit Analytics, en geplande taken. Scripts kunnen in de cloud of ter plaatse worden uitgevoerd.

• HighBond-robot Ondersteunt grootschalige gegevensanalyse met Python/HCL-scripts die rechtstreeks in de robot worden gemaakt, en geplande taken. Scripts kunnen uitsluitend in de cloud worden uitgevoerd.

• Workflow-robot Ondersteunt lichte gegevensanalyse of het automatiseren van delen van uw Diligent One-workflow, met Python/HCL-scripts die rechtstreeks in de robot worden gemaakt, en geplande of gebeurtenisgestuurde taken. Scripts kunnen uitsluitend in de cloud worden uitgevoerd.

  Opmerking

  Om toegang te krijgen tot Workflow-robots moet u zijn toegewezen aan het gebruikerstype Systeembeheerder met een Professional-abonnement.

  Het doel is dat een systeembeheerder met een Professional-abonnement taken kan configureren in Workflow-robots die worden geactiveerd door evenementen in Diligent One. Deze functionaliteit wordt nog ontwikkeld en is nog niet beschikbaar.

Vergelijking van de robottypen

De drie robottypes zijn bedoeld voor verschillende doeleinden en zijn functioneel van elkaar gescheiden. U kunt ACLScript en Python/HCL niet combineren in één robot.

Roboteigenschap	ACL-robot	HighBond-robot	Workflowrobot
Beoogde doel	gegevensanalyse en automatisering		Diligent One-platformautomatisering
Ondersteunde taal	ACLScript	Python Pandas, NumPy, Requests en andere standaard Python-bibliotheken HCL aangepaste Python-bibliotheek (HighBond Command Language)
Locatie voor het maken van scripts	Analytics	Robots
Scriptuitvoeringslocatie	cloud ter plaatse	cloud
Opties voor het uitvoeren van een taak	ingepland handmatig uitvoeren (ad-hoc)		geactiveerd door Diligent One-evenement ingepland handmatig uitvoeren (ad-hoc)
Maximale uitvoeringstijd van een taak	Cloudgebaseerde Robots-agent: 60 minuten Robots Agent ter plaatse: beheerd door klantennetwerk	geen limiet Opmerking Een 12-uursbeperking is gepland, maar nog niet geïmplementeerd. Als een taak te lang blijft lopen en u deze wilt stoppen, kunt u op Taakuitvoering annuleren klikken in het tabblad Taakuitvoeringen.	15 minuten
Maximaal aantal gelijktijdig uitgevoerde taken	5	5	50
Vereiste machtigingen	een medewerker voor de robot worden mate van toegang bepaald door de robotrol van de medewerker (Eigenaar, Bewerker, Controleur)		Gebruikerstype systeembeheerder met een Professional-abonnement

Robotscripteditor

HighBond-robots en Workflow-robots bevatten een geïntegreerde scripteditor voor het schrijven van Python/HCL-scripts en het interactief (handmatig) uitvoeren ervan. De script-editor is gemodelleerd naar het voorbeeld van de Jupyter Notebook App, een ontwikkelomgeving die populair is binnen de datawetenschapsgemeenschap. Het scripteditor gebruikt een Cell-gebaseerde aanpak voor het schrijven van scripts.

Cell-gebaseerde aanpak voor het schrijven van scripts

Het meest opvallende kenmerk van de scripteditor is de mogelijkheid om meerdere cellen te gebruiken voor de afzonderlijke codeblokken waaruit één script bestaat. Als u niet bekend bent met Jupyter Notebook, kan de celgebaseerde aanpak voor het schrijven van scripts er in eerste instantie ingewikkeld uitzien. Het is in feite gemakkelijk te gebruiken en biedt voordelen die u snel zult leren waarderen.

Belangrijkste kenmerken van celgebaseerd scriptontwerp

• Meerdere cellen zijn optioneel U hoeft geen meerdere cellen te gebruiken als u dat niet wilt. U kunt een volledig script schrijven en uitvoeren met behulp van één cel.

• Logische onderdelen Met cellen kunt u een script onderverdelen in logische blokken naar eigen keuze, en deze blokken handmatig afzonderlijk uitvoeren, in willekeurige volgorde, of als een volledige reeks.

  Bijvoorbeeld: een eenvoudige indeling met vier cellen voor een script kan er als volgt uitzien:

  • eerste cel Python-bibliotheken importeren

  • tweede cel gegevens importeren

  • derde cel analyse uitvoeren op de gegevens

  • vierde cel de resultaten van de analyse uitvoeren

• Voordeel van cellen Het gebruik van cellen voor scriptontwikkeling biedt de volgende voordelen:

  • U kunt aan afzonderlijke cellen werken, deze testen en verbeteren, terwijl u tijdelijk de scriptlogica in andere cellen negeert.

  • Nadat u de eerste importcellen eenmaal hebt uitgevoerd, hoeft u deze niet opnieuw uit te voeren terwijl u de volgende cellen ontwikkelt en herhaaldelijk test.

  • U kunt cellen gebruiken om een visuele structuur aan uw scripts op te leggen, waardoor de relatie tussen de verschillende logische blokken gemakkelijker te zien en te begrijpen is voor uzelf of iemand anders.

• Volgordeaanduiding Naast elke cel staat een numerieke aanduiding die de volgorde weergeeft waarin de cel is uitgevoerd tijdens een scriptsessie. Bijvoorbeeld: [7].

  Wanneer u een cel uitvoert, wordt de indicator verhoogd, rekening houdend met eventuele andere cellen die u in de tussentijd hebt uitgevoerd. Dus bijvoorbeeld: een indicator zou kunnen veranderen van [7] naar [10] als u in de tussentijd twee andere cellen had uitgevoerd, of één andere cel twee keer.

• Sessiegeheugen en opgeslagen waarden Dataframes en variabelewaarden die tijdens een scriptingsessie in het geheugen worden vastgehouden, worden bijgewerkt op basis van de volgorde waarin u cellen uitvoert.

  Typisch structureert u cellen om van boven naar beneden opeenvolgend uit te voeren tijdens geplande, onbeheerde scriptuitvoering. Bepaalde dataframes of variabele waarden kunnen geleidelijk worden bijgewerkt op basis van scriptlogica. Als u cellen handmatig in een andere volgorde uitvoert, is de huidige status van een dataframe of een variabelewaarde mogelijk niet wat u verwacht, waardoor er een fout of een onnauwkeurig resultaat kan optreden. Om het dataframe of de variabelewaarde in zijn beoogde staat te herstellen, voert u gewoon alle cellen die verwijzen naar het dataframe of de variabele opnieuw uit in hun beoogde volgorde.

• Weergave van celuitvoer Standaard wordt bij het uitvoeren van een cel alleen de uitvoer van de laatste expressie in de cel weergegeven. Als u de uitvoer van meerdere expressies in een cel wilt zien, kunt u de expressies in afzonderlijke cellen plaatsen. Een handigere aanpak is echter om een configuratieoptie in te stellen in de scripteditor.

  • Cellen configureren om de uitvoer van alle expressies weer te geven:

    from IPython.core.interactiveshell import InteractiveShell
    InteractiveShell.ast_node_interactivity = "all"

  • Cellen resetten om alleen de uitvoer van de laatste expressie weer te geven:

    from IPython.core.interactiveshell import InteractiveShell
    InteractiveShell.ast_node_interactivity = "last_expr"

  Tip

  U kunt de configuratie-instelling gebruiken om indien nodig heen en weer te schakelen tussen de twee modi. Raadpleeg voor aanvullende configuratieopties voor celopbrengst de online documentatie van Jupyter of IPython.

Sneltoetsen in de Robots-scripteditor

Sneltoetsen in de scripteditor zorgen voor gemak en versnellen het ontwikkelproces van een script. In het scripteditorvenster kunt u een lijst met beschikbare sneltoetsen bekijken via een van deze methoden:

• Druk op Ctrl+/

• Klik op het pictogram Sneltoets in de titelbalk

De beschikbare sneltoetsen worden hieronder vermeld.

Sneltoetsen	Actie
Ctrl + Shift + Enter	Geselecteerde cel uitvoeren
Ctrl + Shift + M	Alle cellen opeenvolgend uitvoeren
Ctrl + Shift + Y	Geselecteerde cel en alle cellen erboven uitvoeren
Ctrl + Shift + U	Geselecteerde cel en alle cellen eronder uitvoeren
Ctrl + Shift + I	Scriptuitvoering stoppen
Ctrl + Shift + K Ctrl + Shift + Pijl omhoog	Cel hierboven selecteren
Ctrl + Shift + J Ctrl + Shift + Pijl omlaag	Cel hieronder selecteren
Ctrl + Shift + H Ctrl + Shift + Home	Eerste cel selecteren
Ctrl + Shift + L Ctrl + Shift + End	Laatste cel selecteren
Ctrl + Shift + A	Cel erboven toevoegen
Ctrl + Shift + B	Onderstaande cel toevoegen
Ctrl + Shift + D	Geselecteerde cel verwijderen
Ctrl + Shift + Z	Cel naar boven verplaatsen
Ctrl + Shift + X	Cel naar beneden verplaatsen

Jupyter Notebook-functies die niet zijn opgenomen in de Robots-scripteditor

Zoals hierboven vermeld, is de Robots-scripteditor gemodelleerd naar het voorbeeld van de Jupyter Notebook-app. Deze Jupyter-functies zijn niet opgenomen in de scripteditor, hoewel sommige hiervan in de loop van de tijd mogelijk worden toegevoegd naarmate het product zich verder ontwikkelt:

• Bewerkingen op celniveau:

  • ongedaan maken/opnieuw uitvoeren van celbewerkingen

  • cellen kopiëren/plakken

  • cellen splitsen/samenvoegen

• Cellen met opmaaktaal (voor tekstinhoud)

Scripts opslaan in een logbestand

Wanneer u een Python/HCL-script uitvoert met behulp van een robottaak, hebt u de mogelijkheid om de scriptuitvoer op te slaan in het logbestand dat bij elke taakuitvoering hoort. Het logboek is een JSON-bestand met dezelfde naam als de taak (task_name.json).

Om de optie in te schakelen, selecteert u Scriptuitvoer opslaan in het taakuitvoeringslogbestand wanneer u een versie van een script opslaat en commit. De optie is afzonderlijk configureerbaar voor elke versie van een script. Als u scriptuitvoer wilt opslaan, moet u ervoor zorgen dat u de optie selecteert voor de specifieke scriptversie die de taak uitvoert.

Script-uitvoer verwijst naar alles wat zich in de stdout-stroom bevindt die door een script wordt geproduceerd. Wanneer u een script interactief uitvoert, is stdout doorgaans alles wat het script op het scherm weergeeft of afdrukt. In wezen legt u door Scriptuitvoer opslaan in het taakuitvoeringslogbestand te selecteren alles wat op het scherm wordt weergegeven permanent vast. Deze vastgelegde uitvoer kan nuttig zijn om te bekijken tijdens het ontwikkelen en oplossen van problemen in scripts.

Aanvullende informatie:

• De optie is alleen van toepassing op taken Ook al selecteert u Scriptuitvoer opslaan in het taakuitvoeringslogbestand in de Robots-scripteditor, de optie is alleen van toepassing op scripts die door een robottaak worden uitgevoerd. De optie heeft geen effect wanneer u een script interactief uitvoert in de scripteditor.

• Foutmeldingen in het logboekbestand van de taakuitvoering Python-foutmeldingen (de stderr-stroom) worden altijd opgenomen in het logboekbestand van de taakuitvoering, ongeacht hoe u Scriptuitvoer opslaan in het logboekbestand van de taakuitvoering configureert.

• Het taakuitvoeringslogboekbestand openen Voor elke taakuitvoering is een logboekbestand beschikbaar op het tabblad Taakuitvoeringen. Selecteer een taakuitvoering en het logbestand verschijnt in het gedeelte Uitvoer in het zijpaneel Details taakuitvoering. U kunt het bestand downloaden naar uw computer om het te bekijken.

De overstap maken van ACLScript naar Python en HCL

Python is een programmeertaal voor algemene doeleinden en is aanzienlijk complexer dan ACLScript, een relatief eenvoudige scripttaal die oorspronkelijk is ontworpen voor het domein van auditanalyses.

Onze bedoeling is dat HCL op den duur veel van de opdrachten en functies die beschikbaar zijn in ACLScript zal repliceren. Om aan de slag te gaan met HCL, onze aangepaste Python-bibliotheek, is het noodzakelijk dat u ten minste over elementaire Python-vaardigheden beschikt. Het advies voor degenen die de overstap van ACLScript naar Python/HCL willen maken, is om een goede inleidende cursus Python te volgen.

Python-codeerconventies

U moet wennen aan bepaalde coderingsconventies die in Python en HCL wel verplicht zijn, maar in ACLScript niet:

• Hoofdlettergevoeligheid Python- en HCL-syntaxis zijn hoofdlettergevoelig, terwijl ACLScript-syntaxis dit niet is.

  In Python:

  • print("Hello World!") werkt

  • PRINT("Hello World!") geeft een foutmelding

• Niet afkorten Python- en HCL-functie-, methode- en parameternamen moeten volledig worden uitgeschreven. In tegenstelling tot ACLScript worden afkortingen niet ondersteund.

• Inspringen is belangrijk Python gebruikt inspringen om controlestructuren zoals voorwaardelijke instructies en lussen te implementeren. Onjuiste inspringing veroorzaakt fouten. ACLScript negeert inspringing.

Python externe bibliotheken

Python ondersteunt een groot aantal externe bibliotheken of pakketten die u kunt installeren om de functionaliteit van de kerninstallatie van Python en de Python-standaardbibliotheek uit te breiden. Een Python externe bibliotheek is een verzameling gerelateerde codemodules die zijn ontworpen om specifieke taken uit te voeren die verder gaan dan wat mogelijk is met de kern van Python en de standaardbibliotheek. Of het maakt bepaalde dingen sneller en makkelijker om te doen dan in standaard Python.

Externe bibliotheken opgenomen in Diligent One Python

De Diligent One-installatie van Python bevat standaard bepaalde externe bibliotheken, dus u hoeft deze niet expliciet te installeren. Met uitzondering van Diligent's eigen HCL Python-bibliotheek moet u de vooraf geïnstalleerde bibliotheken importeren om ze te kunnen gebruiken in daaropvolgende Python/HCL-scriptlogica.

Externe bibliotheken die vooraf zijn geïnstalleerd in de Diligent One Python-omgeving:

Bibliotheek	Beschrijving	Python-importinstructies
HCL	De HCL-bibliotheek, oftewel HighBond Command Language, is de aangepaste Python-bibliotheek van Diligent voor domeingerichte gegevensanalyse en Diligent One-automatisering.	niet vereist
Pandas	De Pandas-bibliotheek biedt een krachtige set hulpmiddelen voor gegevensmanipulatie en gegevensanalyse in Python, waaronder dataframes, die spreadsheetachtige of tabelachtige tweedimensionale arrays van gegevens zijn.	pandas importeren of pandas als pd importeren (maakt optioneel een korte alias voor de bibliotheeknaam)
NumPy	De NumPy-bibliotheek biedt snelle en krachtige wetenschappelijke berekeningen in Python, waaronder elementaire algebraïsche en statistische bewerkingen, geavanceerde wiskundige bewerkingen, en het maken en uitvoeren van berekeningen op multidimensionale arrays.	numpy importeren of numpy als np importeren (maakt optioneel een korte alias voor de bibliotheeknaam)
Aanvragen	De Requests-bibliotheek biedt een lichtgewicht syntax voor het maken van HTTP-aanvragen in Python en het interageren met webgebaseerde API's.	aanvragen importeren of aanvragen als req importeren (maakt optioneel een korte alias voor de bibliotheeknaam)
Cryptography	De Cryptography-bibliotheek ondersteunt het integreren van cryptografische algoritmen in Python.	cryptography importeren of cryptography als crypt importeren (maakt optioneel een korte alias voor de bibliotheeknaam)

Externe bibliotheken installeren

HighBond-robots ondersteunen de installatie van extra externe bibliotheken naast degene die vooraf zijn geïnstalleerd in de Diligent One Python-omgeving. Om een extra bibliotheek te installeren, gebruikt u pip, een hulpmiddel voor het downloaden en installeren van Python-pakketten. Standaard downloadt pip de pakketten van de Python Package Index (PyPI), een open-source opslagplaats voor Python-software. U kunt ook pip gebruiken om pakketten van elders te installeren.

Bijvoorbeeld: om pyexcel te installeren, een Python-bibliotheek voor het werken met Excel-bestanden en -gegevens, gebruik je deze opdracht in de Robots-scripteditor:

pip install pyexcel

Zelfs als u een externe bibliotheek installeert, is er geen garantie dat de Robots-scripteditor alle functionaliteit van de externe bibliotheek ondersteunt. Bijvoorbeeld: het ondersteunt mogelijk niet de weergave van grafieken en diagrammen die beschikbaar zijn in bepaalde externe bibliotheken.

Python en HCL gebruiken om met API's te werken

U kunt Python/HCL-scripts in Robots gebruiken om met API's te werken – zowel API's van derden als de eigen API van Diligent One.

Met een API van derden werken

Om met een API van derden te werken, begin je met het importeren van de Python Requests-bibliotheek in de Robots-scripteditor:

import requests

U kunt nu API-aanvragen doen met behulp van de syntax van Python's request en antwoorden ontvangen. Voor een eenvoudig voorbeeld van het gebruik van Python om een API-aanvraag van derden te doen in Robots, zie Deel 3: Breid uw bereik uit in Aan de slag met Robots-scripting en de Diligent HighBond API.

Het in detail uitleggen hoe Python te gebruiken met API's van derden valt buiten het bereik van onze documentatie. Er zijn echter veel online bronnen beschikbaar die gedetailleerde begeleiding kunnen bieden.

Werken met de HighBond API

De HighBond API is de ontwikkelaarsinterface voor het Diligent One Platform. U kunt de API gebruiken om Diligent One-interacties en -workflow te automatiseren, rapportages te maken en Diligent One te integreren met andere systemen in uw organisatie.

HCL bevat methoden die de interactie met de HighBond API eenvoudig maken. Voor meer informatie raadpleegt u HCL HighBond API-methodes.

U kunt ook de Python Requests-bibliotheek gebruiken met de HighBond API. We raden echter aan om de HCL-methoden te gebruiken voor het gemak en de eenvoud.

Voor een inleidende tutorial over het gebruik van Python en HCL met de HighBond API, zie Aan de slag met Robots-scripting en de Diligent HighBond API.