Studio-sessiehandleiding

De Bluebeam Developer Portal, voor integratieontwikkeling, is alleen beschikbaar voor actieve klanten, kanaalpartners en softwarepartners in de regio's VS, AU, DE, VK en SE.

U kunt een Studio-sessie zien als een digitale vergaderruimte waarin PDF-tekeningen gelijktijdig of asynchroon van aantekeningen kunnen worden voorzien. Deze handleiding beschrijft de algemene levenscyclus van een Studio-sessie en bevat codevoorbeelden. Voor meer informatie over Studio en Studio-sessies in het algemeen, bezoek onze Studio FAQ-pagina.

U kunt deze handleiding volgen en veel van de aanroepen in het Studio-gedeelte van onze API-documentatie uitproberen. Zie onze handleiding Aan de slag in de Bluebeam Developer Portal voor instructies over het verkrijgen van een geldige toegangstoken.

Er zijn regiospecifieke basis-URL's die Toepassen op alle eindpunten:

- VS: https://api.bluebeam.com

- DU: https://api.bluebeamstudio.de

- AU: https://api.bluebeamstudio.com.au

- UK: https://api.bluebeamstudio.co.uk

- SE: https://api.bluebeamstudio.se

Bijvoorbeeld: https://api.bluebeam.com/publicapi/v1/sessions in de VS zou https://api.bluebeamstudio.com.au/publicapi/v1/sessions in Australië zijn.

Levenscyclus van Studio-sessies

De levenscyclus van een Studio-sessie kan worden gesplitst in 4 delen:

  1. Initialisatie – Opent de "digitale vergaderruimte"

  2. Voeg PDF's toe aan de sessie om te bekijken en te markeren

  3. Voeg gebruikers toe aan de sessie, zodat ze deze kunnen bekijken en markeren

  4. Finalisatie – Sluit de sessie en retourneert de gemarkeerde PDF's naar hun oorspronkelijke systeem

De eerste fase in de levenscyclus van een Studio-sessie is de creatie ervan. Om te beginnen, maakt u een POST -opdracht naar het Sessions-eindpunt met de volgende parameters.

Eindpunt

copy 
https://api.bluebeam.com/publicapi/v1/sessions

Zorg ervoor dat u client_id in de header van uw aanvraag opneemt.

Aanvraagparameters

Naam

Beschrijving

Waardetype / Mogelijke waarden

Naam

Sessienaam

String

Notification

Ja: De huidige gebruiker wordt geabonneerd op e-mailmeldingen over wijzigingen in deze Sessie.

Nee: De huidige gebruiker ontvangt geen e-mailmeldingen over wijzigingen in deze Sessie.

Booleaanse

Restricted

Ja: Beperkt de Sessie tot alleen e-mailadressen die zijn uitgenodigd of toegevoegd.

Nee: De Sessie blijft open voor iedereen die de 9-cijferige Sessie-ID heeft.

Booleaanse

SessionEndDate

Zodra deze datum is bereikt, worden alle deelnemers, met uitzondering van de gastheer/gastvrouw, uit de sessie verwijderd.

Must be formatted in UTC format.

DefaultPermissions

Deze machtigingenset zal van toepassing zijn op alle gebruikers die aan deze Sessie zijn toegevoegd, met uitzondering van de Host (de huidige gebruiker). De Host krijgt Volledig beheer.

Hieronder worden de soorten machtigingen en de machtigingen zelf gedefinieerd.

Machtiging

Beschrijving

Waardetype / Mogelijke waarden

Type

Soort toestemming

SaveCopy – Geef deelnemers de mogelijkheid om op te slaan als.

PrintCopy – Hiermee kunnen deelnemers PDF's afdrukken die bij de sessie zijn inbegrepen.

Markup – Geef deelnemers de mogelijkheid om Markeringen aan te brengen.

AddDocuments – Hiermee kunnen deelnemers nieuwe documenten aan de sessie toevoegen.

FullControl – Geef deelnemers beheerdersrechten voor de sessie.

MarkupAlert – Hiermee kunnen deelnemers tijdens de Sessie Markeringen verzenden en ontvangen.

Allow

Machtigingsstatus

Toestaan, Weigeren, Standaard

Einddatum sessie
Einddatums voor sessies zijn niet verplicht, maar als u een einddatum voor sessies selecteert, worden deelnemers aan de sessie 7 dagen, 2 dagen en 24 uur vóór de vervaldatum per e-mail op de hoogte gesteld.

cURL-voorbeeld

copy 
cURL [https://api.bluebeam.com/publicapi/v1/sessions](https://api.bluebeam.com/publicapi/v1/sessions) \
-H "Authorization: Bearer {valid access_token}" \
-H "Content-Type: Application/JSON" \
-H "client_id: [your client_id]" \
-d '{

    "Name":"Pied Piper Acquisition Review",

    "Notification": true,

    "Restricted": true,

    "SessionEndDate": "2016-08-17T21:09:07.5174221Z",

    "DefaultPermissions":[  
      {  
        "Type":"SaveCopy",  
        "Allow":"Allow"  
      },  
      {  
        "Type":"PrintCopy",  
        "Allow":"Allow"  
      },  
      {  
        "Type":"Markup",  
        "Allow":"Allow"  
      },  
      {  
        "Type":"MarkupAlert",  
        "Allow":"Allow"  
      },  
      {  
        "Type":"AddDocuments",  
        "Allow":"Deny"  
      }  
    ]
}' \
-X POST

Machtigingen
Huidige Studio-gebruikers zijn vaak gewend aan specifieke standaardinstellingen voor machtigingen. Het is altijd een goed idee om te controleren wat de standaardrechten zouden moeten zijn of om gebruikers toe te staan hun eigen rechten te kiezen. Wanneer u de Bluebeam API gebruikt om machtigingen in te stellen, is 'Weigeren' de standaardwaarde.

Reactie-instantie

copy 
{
    "$id": "1",
    "Id": "123-456-789"
}

De volgende stap is het toevoegen van de PDF-bestanden. Het toevoegen van bestanden is een proces van 3 stappen:

  1. Maak het metadatablok voor het bestand via de Bluebeam API

  2. Upload het bestand rechtstreeks naar AWS

  3. Bevestig upload via de Bluebeam API

Opmerking: Studio-sessies ondersteunen geen PDF/A-bestanden.
Omdat PDF/A een archiefformaat is, kan het niet worden bewerkt en mislukt stap 4 hieronder.

Eindpunt

copy 
https://api.bluebeam.com/publicapi/v1/sessions/{sessionId}/files

Parameters

Naam

Beschrijving

Waardetype / Mogelijke waarden

Naam

Naam van het bestand

String eindigend op ".pdf"

Source

Bronpad: dit kan u helpen later in het proces te identificeren waar het bestand vandaan kwam

String

Size

Bestandsgrootte; laat nul staan zodat de server dit kan berekenen

Geheel getal

CRC

Laat nul staan zodat de server kan berekenen

String

cURL-voorbeeld

copy 
cURL [https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files](https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files) \
-H "Authorization: Bearer {valid access_token}" \
-H "Content-Type: Application/JSON" \
-H "client_id: [your client_id]" \
-d '{  
      "Name":"Pied_Piper_Acquisition.pdf",  
      "Source":"[https://portfolio.raviga.com/primarybets/piedpiper/legaldocs/Pied_Piper_Acquisition.pdf](https://portfolio.raviga.com/primarybets/piedpiper/legaldocs/Pied_Piper_Acquisition.pdf)"
    }' \
-X POST

Voorbeeldreactie

copy 
{
  "Id": 1234567
  "UploadUrl":"{upload file to this URL}"
  "UploadContentType":"Application/PDF"
}

Uploadvenster
De upload-URL is 10 minuten geldig om het uploaden te starten.

Zodra u een Metadata Block-placeholder voor uw bestand hebt, dient u een PUT -aanvraag in voor de geretourneerde UploadURL van de vorige POST aanvraag. Neem het volgende op in de header van uw PUT aanvraag:

  • "x-amz-server-side-encryption" met waarde "AES256"

  • "Content-Type" met waarde "application/pdf"

Eindpunt

copy 
https://api.bluebeam.com/publicapi/v1/sessions/{sessionId}/files/{id}/confirm-upload

cURL-voorbeeld

copy 
cURL [https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files/1234567/confirm-upload](https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files/1234567/confirm-upload) \
-H "Authorization: Bearer {valid access_token}" \
-H "client_id: [your client id]" \
-X POST

Reactie

Als het lukt, krijgt u een 204 respons. Voor fouten kunt u de algemene HTML-responscodes onderaan onze Authenticatiehandleiding raadplegen.

 

Nu u een sessie met PDF's hebt, is het tijd om gebruikers aan de sessie toe te voegen. De initiator van de sessie (de huidige gebruiker) wordt automatisch de host van de sessie en wordt automatisch toegevoegd aan de gebruikers van de sessie. Er kunnen altijd meer gebruikers worden toegevoegd terwijl de sessie actief is. Er zijn 2 methoden om gebruikers toe te voegen:

Deze methode is het meest geschikt om gebruikers uit te nodigen die nog geen Studio-account hebben. Er wordt een e-mail verzonden naar de uitgenodigde met de mogelijkheid om een gratis Studio-account aan te maken.

Eindpunt

copy 
https://api.bluebeam.com/publicapi/v1/sessions/{sessionId}/invite

Parameters

Naam

Beschrijving

Email

E-mailadres waarnaar de uitnodiging moet worden verzonden

Bericht

Aangepast bericht dat in de e-mail wordt weergegeven

Voorbeeld

copy 
cURL https://api.bluebeam.com/publicapi/v1/sessions/{session}/invite \
-H "Authorization: Bearer {token}" \
-H "Content-Type: Application/JSON" \
-H "client_id: {client_id}" \
-d '{  
      "E-mail":"gavin.belson@hooli.com",  
      "Bericht":"Neem deel aan deze sessie om documenten met betrekking tot de overname van Pied Piper te bekijken."
    }' \
-X POST

Reactie

Als het lukt, krijgt u een 204 respons. Voor fouten kunt u de algemene HTML-responscodes onderaan onze Authenticatiehandleiding raadplegen.

OF

Deze methode werkt het beste als u weet dat het e-mailadres al aan een Studio-account is gekoppeld en u wilt dat ze aan een Studio-sessie worden toegevoegd zonder dat u zich hiervoor hoeft aan te melden. Als de gebruiker geen account heeft of niet zeker weet of hij/zij er wel een heeft, gebruikt u Methode A: Gebruiker uitnodigen. Met Methode B: Gebruiker toevoegen wordt de gebruiker toegevoegd aan de deelnemers van de Studio-sessie. De Studio-sessie verschijnt onder hun bijgewoonde sessies op het tabblad Studio in de Revu-interface.

Eindpunt

copy 
https://api.bluebeam.com/publicapi/v1/sessions/{sessionId}/users

Parameters

Naam

Beschrijving

Email

E-mailadres van het bekende Studio-account

SendEmail

Booleaans; Ja: stuur een e-mail naar de uitgenodigde, Nee: stuur geen e-mailmelding naar de uitgenodigde

Bericht

Aangepast bericht dat in de e-mail wordt weergegeven

Voorbeeld

copy 
cURL [https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/users](https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/users)
-H "Authorization: Bearer {valid access_token}" \
-H "Content-Type: Application/JSON" \
-H "client_id: [your client id]" \
-d '{  
      "E-mail": "peter.gregory@raviga.com",
      "SendEmail": true,
      "Bericht": "Zoals gevraagd, is hier de sessie om de documenten met betrekking tot de overname van Pied Piper te bekijken."
    }' \
-X POST

Reactie

Als het lukt, krijgt u een 204 respons. Voor fouten kunt u de algemene HTML-responscodes onderaan onze Authenticatiehandleiding raadplegen.

Voorbeeldsessie-uitnodigingsmail

 

Om een sessie te beëindigen (meestal nadat de deelnemers alle markeringen hebben aangebracht of nadat de sessie is verlopen), moet de status worden gewijzigd, moeten de bestanden worden verwerkt en moet de sessie zelf op de juiste manier worden verwijderd.

Als u de status van een Sessie instelt op Bezig met afronden, worden alle gebruikers uit de Sessie verwijderd, behalve de host. Dit wordt gedaan om te voorkomen dat er verdere wijzigingen in de Sessiebestanden worden aangebracht nadat ze zijn gedownload.

Eindpunt

copy 
https://api.bluebeam.com/publicapi/v1/sessions/{id}

Voorbeeld

copy 
cURL https://api.bluebeam.com/publicapi/v1/sessions/123-456-789 \
-H "Authorization: Bearer {valid access_token}" \
-H "Content-Type: Application/JSON" \
-H "client_id: [your client id]" \
-d '{"Status": "Finalizing"}' \
-X PUT

Het downloaden van de gemarkeerde Sessiebestanden is een proces dat uit twee delen bestaat. Volg de onderstaande stappen voor elk bestand in de sessie.

i. Maak een momentopname

Tijdens een sessie worden PDF's en markeringen apart opgeslagen. Een Momentopname combineert de PDF-inhoud met de markeringslaag tot één PDF, zodat de Markeringen buiten de Studio-sessie op de PDF zichtbaar zijn.

Eindpunt

copy 
https://api.bluebeam.com/publicapi/v1/sessions/{sessionId}/files/{id}/snapshot

Voorbeeld

copy 
cURL [https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files/1234567/snapshot](https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files/1234567/snapshot) \
-H "Authorization: Bearer {valid access_token}" \
-H "client_id: [your client id]" \

ii. Controleer de status van de momentopname en download deze indien voltooid.

Doe een GET -aanvraag naar het Momentopname-eindpunt totdat de Status Complete of Error is.

  • Indien Error: Er wordt een foutmelding weergegeven die aan de gebruiker kan worden getoond.

  • Indien Complete: Gebruik de DownloadUrl om de momentopname te downloaden

Eindpunt

copy 
https://api.bluebeam.com/publicapi/v1/sessions/{sessionId}/files/{id}/snapshot

Voorbeeld

copy 
cURL [https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files/1234567/](https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files/1234567/)
-H "Authorization: Bearer {valid access_token}" \
-H "client_id: [your client id]" \
-X GET

Reactie-instantie

copy 
{
    "Status": "Complete",
    "StatusTime": "{The last time the Status was changed}",
    "LastSnapshotTime": "{Time of last successful Snapshot}",
    "DownloadUrl": "{A download URL for the last successful Snapshot}"
}

Statusopties

Status

Beschrijving

NoSnapshot

Wanneer een Momentopname nog nooit is aangeroepen voor een bestand

Requested

De Momentopname-taak is nog niet gestart, maar we hebben het verzoek ontvangen

InProgress

De Momentopname-taak is bezig

Complete

De Momentopname-taak is voltooid en kan worden gedownload via DownloadUrl

Error

De Momentopname-taak is mislukt. De status bevat een foutmelding.

Nu u de gemarkeerde PDF's hebt, kunt u de sessie verwijderen door een DELETE -verzoek te sturen naar het sessie-ID-eindpunt.

Eindpunt

copy 
https://api.bluebeam.com/publicapi/v1/sessions/{id}

Voorbeeld voor het afsluiten van een sessie

copy 
cURL [https://api.bluebeam.com/publicapi/v1/sessions/123-456-789](https://api.bluebeam.com/publicapi/v1/sessions/123-456-789) \
-H "Authorization: Bearer {valid access_token}" \
-H "Content-Type: Application/JSON" \
-H "client_id: [your client id]" \
-X DELETE

 

Conclusie

Door het bestand terug te zetten naar de oorspronkelijke locatie en de sessie te archiveren, is de typische levenscyclus van een Studio-sessie voltooid. Hoewel er veel verschillende manieren zijn om met Studio-sessies te werken, hopen we dat u met deze walkthrough een goed begrip heeft gekregen van de basisprincipes.

 

Zie ook:

Hulpbronnen

Revu 21

Developer Portal

Developer Portal

Deze handleiding voor de Developer Portal behandelt de algemene levenscyclus van een Studio-sessie en bevat codevoorbeelden.