Flussi di lavoro degli accordi in Node.js

Molte applicazioni e processi aziendali richiedono documentazione come proposte e accordi. Con i documenti PDF i file risultano più sicuri e meno modificabili. Offre inoltre il supporto per la firma digitale, per consentire ai clienti di completare i documenti in modo semplice e veloce. Adobe Acrobat Services Le API integrano facilmente le funzionalità PDF nelle applicazioni Web.

Cosa puoi imparare

In questo tutorial pratico, scopri come aggiungere servizi PDF a un’applicazione Node.js per digitalizzare un processo di accordo.

API e risorse pertinenti

Impostazione Adobe Acrobat Services

Per iniziare, configura le credenziali da utilizzare Adobe Acrobat Services. Registra un account e utilizza Node.js QuickStart per verificare il funzionamento delle credenziali prima di integrare la funzionalità in un'applicazione di grandi dimensioni.

Per prima cosa, ottieni un account sviluppatore di Adobe. Quindi, sul Introduzione , seleziona la pagina Introduzione opzione in Crea nuove credenziali. Puoi registrarti per la versione di prova gratuita che fornisce 1.000 transazioni di documenti che possono essere utilizzati in sei mesi.

Nella pagina Creazione di nuove credenziali seguente viene richiesto di scegliere tra l'API PDF Embed e l'API PDF Services.

Seleziona API di PDF Services.

Immetti un nome per l’applicazione e seleziona la casella etichettata Creare un esempio di codice personalizzato. Selezionando questa casella, le credenziali vengono incorporate automaticamente nell'esempio di codice. Se si lascia deselezionata questa casella, è necessario aggiungere manualmente le credenziali all'applicazione.

Seleziona Node.js per il tipo di applicazione e fare clic su Crea credenziali.

Pochi istanti dopo, un file .zip inizia a essere scaricato con un progetto di esempio che include le tue credenziali. Pacchetto Node.js per Acrobat Services è già incluso nel codice del progetto di esempio.

Configurazione manuale del progetto di esempio

Se scegliete di non scaricare un progetto di esempio dalla pagina Crea nuove credenziali, potete anche impostare il progetto manualmente.

Scarica il codice (senza credenziali incorporate) da GitHub. Se si utilizza questa versione del codice, è necessario aggiungere le credenziali al file pdftools-api-credentials.json prima di utilizzare:

{
  "client_credentials": {
    "client_id": "<client_id>",
    "client_secret": "<client_secret>"
  },
  "service_account_credentials": {
    "organization_id": "<organization_id>",
    "account_id": "<technical_account_id>",
    "private_key_file": "<private_key_file_path>"
  }
}

Per la propria applicazione, è necessario copiare il file della chiave privata e i file delle credenziali nell'origine dell'applicazione.

È necessario installare il pacchetto Node.js per Acrobat Services. Per installare il pacchetto, utilizza il comando seguente:

npm install --save @adobe/documentservices-pdftools-node-sdk

Impostazione della registrazione

In questi esempi viene utilizzato Express per il framework dell'applicazione. e log4js per la registrazione delle applicazioni. Con log4js, potete indirizzare facilmente l'accesso alla console o a un file:

const log4js = require('log4js');
const logger = log4js.getLogger();
log4js.configure( {
    appenders: { fileAppender: { type:'file', filename: './logs/applicationlog.txt'}},
    categories: { default: {appenders: ['fileAppender'], level:'info'}}
});

logger.level = 'info';
logger.info('Application started')

Il codice riportato sopra scrive i dati registrati in un file in ./logs/applicationlog.txt. Se invece desideri che scriva sulla console, puoi commentare la chiamata su log4js.configure.

Conversione di file Word in PDF

Gli accordi e le proposte vengono spesso scritti in un’applicazione di produttività, come Microsoft Word. Per accettare documenti in questo formato e convertire il documento in PDF, è possibile aggiungere funzionalità per l'applicazione. Diamo un'occhiata a come caricare e salvare un documento in un'applicazione Express e salvarlo nel file system.

Nel HTML dell’applicazione, aggiungi un elemento file e un pulsante per avviare il caricamento:

<input type="file" name="source" id="source" />
<button onclick="upload()" >Upload</button>

In JavaScript della pagina, caricare il file in modo asincrono utilizzando la funzione di recupero:

function upload()
{
  let formData = new FormData();
  var selectedFile = document.getElementById('source').files[0];
  formData.append("source", selectedFile);
  fetch('documentUpload', {method:"POST", body:formData});
}

Scegli una cartella per accettare i file caricati. L'applicazione richiede un percorso per questa cartella. Trovare il percorso assoluto utilizzando un percorso relativo unito a __dirname:

const uploadFolder = path.join(__dirname, "../uploads");

Poiché il file viene inviato tramite post, è necessario rispondere a un messaggio di post sul lato server:

router.post('/', (req, res, next) => {
  console.log('uploading')
  if(!req.files || Object.keys(req.files).length === 0) {
  return res.status(400).send('No files were uploaded');
  }

  const uploadPath = path.join(uploadFolder, req.files.source.name);
  var buffer = req.files.source.data;
  var result = {"success":true};
  fs.writeFile(uploadPath, buffer, 'binary', (err)=> {
    if(err) {
      result.success = false;
    }
    res.json(result);
  });
});

Dopo l'esecuzione di questa funzione, il file viene salvato nella cartella di caricamento delle applicazioni ed è disponibile per ulteriori elaborazioni.

Quindi, converti il file dal suo formato nativo in PDF. Il codice di esempio scaricato in precedenza contiene uno script denominato create-pdf-from-docx.js per la conversione di un documento in PDF. La seguente funzione: convertDocumentToPDF, prende un documento caricato e lo converte in un PDF in una cartella diversa:

function convertDocumentToPDF(sourcePath, destinationPath)
{
  try {
    const credentials = PDFToolsSDK.Credentials
    .serviceAccountCredentialsBuilder()
    .fromFile("pdftools-api-credentials.json")
    .build();

    const executionContext =
      PDFToolsSDK.ExecutionContext.create(credentials),
    createPdfOperation = PDFToolsSDK.CreatePDF.Operation.createNew();

    const docxReadableStream = fs.createReadStream(sourcePath);
    const input = PDFToolsSDK.FileRef.createFromStream(
      docxReadableStream,
      PDFToolsSDK.CreatePDF.SupportedSourceFormat.docx);
    createPdfOperation.setInput(input);

    createPdfOperation.execute(executionContext)
    .then(result => result.saveAsFile(destinationPath))
    .catch(err => {
      logger.erorr('Exception encountered while executing operation');
    })
  }
  catch(err) {
    logger.error(err);
  }
}

Con il codice è possibile osservare uno schema generale:

Il codice crea un oggetto credenziali e un contesto di esecuzione, inizializza alcune operazioni, quindi esegue l'operazione con il contesto di esecuzione. Potete vedere questo pattern in tutto il codice di esempio.

Aggiungendo alcune aggiunte alla funzione di caricamento in modo da richiamarla, i documenti di Word caricati dagli utenti vengono ora automaticamente convertiti in PDF.

Il codice seguente crea il percorso di destinazione per il PDF convertito e avvia la conversione:

const documentFolder = path.join(__dirname, "../docs");
var extPosition = req.files.source.name.lastIndexOf('.') - 1;
if(extPosition < 0 ) {
  extPosition = req.files.source.name.length
}
const destinationName = path.join(documentFolder,
  req.files.source.name.substring(0, extPosition) + '.pdf');
console.log(destinationName);

logger.info('converting to ${destinationName}')
  convertDocumentToPDF(uploadPath, destinationName);

Conversione di altri tipi di file in PDF

Document Toolkit converte altri formati in PDF, ad esempio static HTML, un altro tipo di documento comune. Il toolkit accetta documenti HTML inseriti in un pacchetto come file .zip contenente tutte le risorse a cui fa riferimento il documento (file CSS, immagini e altri file) nello stesso file .zip. Il documento HTML stesso deve essere denominato index.html e inserito nella directory principale del file .zip.

Per convertire un file .zip contenente HTML, utilizzate il codice seguente:

//Create an HTML to PDF operation and provide the source file to it
htmlToPDFOperation = PDFToolsSdk.CreatePDF.Operation.createNew();
const input = PDFToolsSdk.FileRef.createFromLocalFile(sourceZipFile);
htmlToPDFOperation.setInput(input);

// custom function for setting options
setCustomOptions(htmlToPDFOperation);

// Execute the operation and Save the result to the specified location.
htmlToPDFOperation.execute(executionContext)
  .then(result => result.saveAsFile(destinationPdfFile))
  .catch(err => {
    logger.error('Exception encountered while executing operation');
});

La funzione setCustomOptions specifica altre impostazioni di PDF, ad esempio le dimensioni della pagina. Qui puoi vedere come la funzione imposta le dimensioni di pagina su 11,5 x 11 pollici:

const setCustomOptions = (htmlToPDFOperation) => {
  const pageLayout = new PDFToolsSdk.CreatePDF.options.PageLayout();
  pageLayout.setPageSize(11.5, 8);

  const htmlToPdfOptions =
    new PDFToolsSdk.CreatePDF.options.html.CreatePDFFromHtmlOptions.Builder()
    .includesHeaderFooter(true)
    .withPageLayout(pageLayout)
    .build();
  htmlToPDFOperation.setOptions(htmlToPdfOptions);
};

All’apertura di un documento HTML che contiene alcuni termini, nel browser viene visualizzato quanto segue:

L'origine di questo documento è composta da un file CSS e da un file HTML:

Dopo l’elaborazione del file HTML, il testo in formato PDF sarà lo stesso:

Aggiunta di pagine

Un’altra operazione comune con i file PDF è aggiungere alla fine delle pagine che possono contenere testo standard, ad esempio un elenco di termini. Il toolkit per documenti può combinare più documenti PDF in un unico documento. Se disponi di un elenco di percorsi dei documenti (qui nella sourceFileList), potete aggiungere i riferimenti dei file di ogni file a un oggetto per un'operazione di combinazione.

Quando viene eseguita l’operazione di combinazione, viene fornito un singolo file con il contenuto di origine. È possibile utilizzare saveAsFile sull'oggetto per salvare in modo permanente il file nell'archiviazione.

const executionContext = PDFToolsSDK.ExecutionContext.create(credentials);
var combineOperation = PDFToolsSDK.CombineFiles.Operation.createNew();

sourceFileList.forEach(f => {
  var combinedSource = PDFToolsSDK.FileRef.createFromLocalFile(f);
  console.log(f);
  combineOperation.addInput(combinedSource);
});


combineOperation.execute(executionContext)
  .then(result=>result.saveAsFile(destinationFile))
  .catch(err => {
    logger.error(err.message);
});

Visualizzazione di documenti PDF

Hai eseguito diverse operazioni sui file PDF, ma alla fine, l'utente deve visualizzare i documenti. Puoi incorporare il documento in una pagina Web utilizzando l’API PDF Embed di Adobe.

Nella pagina in cui è visualizzato il PDF, aggiungi un <div /> per contenere il documento e assegnargli un ID. Questo ID verrà utilizzato a breve. Nella pagina Web, includi un <script /> riferimento alla libreria JavaScript di Adobe:

<script src="https://documentcloud.adobe.com/view-sdk/main.js"></script>

L’ultimo bit di codice necessario è una funzione che visualizza il documento una volta caricato l’API JavaScript di Adobe PDF Embed. Quando ricevete una notifica che avvisa che lo script è stato caricato tramite un evento adobe_dc_view_sdk.ready, create un nuovo oggetto AdobeDC.View. Questo oggetto richiede l'ID client e l'ID dell'elemento creato in precedenza. Trova il tuo ID client nella Console Adobe Developer. Quando si visualizzano le impostazioni per l'applicazione creata durante la generazione delle credenziali precedenti, viene visualizzato l'ID client.

Altre opzioni PDF

La Demo delle API di Adobe PDF Embed consente di visualizzare in anteprima le varie altre opzioni per l’incorporamento di documenti PDF.

Puoi attivare e disattivare varie opzioni e vedere immediatamente come vengono eseguite. Quando trovi una combinazione che ti piace, fai clic sul pulsante </> Genera codice per generare il codice HTML effettivo utilizzando tali opzioni.

Aggiunta di firme digitali e sicurezza

Una volta che il documento è pronto, è possibile aggiungervi firme digitali per l’approvazione utilizzando Adobe Sign. Questa funzionalità funziona in modo leggermente diverso rispetto a quella utilizzata finora. Per le firme digitali, un’applicazione deve essere configurata per utilizzare OAuth per l’autenticazione dell’utente.

Il primo passaggio della configurazione dell'applicazione è registrare l'applicazione per utilizzare OAuth per Adobe Sign. Una volta effettuato l’accesso, accedi alla schermata per creare le applicazioni facendo clic su Account, quindi aprire il API ADOBE SIGN e fare clic su Applicazioni API per aprire l'elenco delle applicazioni registrate.

Per creare una nuova voce dell’applicazione, fai clic sull’icona più in alto a destra.

Nella finestra visualizzata, immetti il nome dell’applicazione e il nome visualizzato. Seleziona Cliente per il dominio, quindi fare clic su Salva.

Dopo aver creato l'applicazione, è possibile selezionarla dall'elenco e fare clic su Configurazione di OAuth per l’applicazione. Seleziona le opzioni. Nell’URL di reindirizzamento, immetti l’URL dell’applicazione. Qui puoi inserire più URL. Per l'applicazione che state testando, il valore è:

http://localhost:3000/signed-in

Il processo di utilizzo di OAuth per ottenere un token è standard. L’applicazione indirizza un utente a un URL per l’accesso. Una volta effettuato l'accesso, l'utente viene reindirizzato all'applicazione con ulteriori informazioni nei parametri di query della pagina.

Per l’URL di accesso, l’applicazione deve passare l’ID client, l’URL di reindirizzamento e un elenco degli ambiti necessari.

Il modello per l'URL è simile al seguente:

https://secure.adobesign.com/public/oauth?
  redirect_uri=&
  response_type=code&
  client_id=&
  scope=

All’utente viene richiesto di accedere al proprio ID per Adobe Sign. Dopo aver effettuato l’accesso, viene richiesto se fornire le autorizzazioni all’applicazione.

Se l'utente fa clic su Consenti accesso nell’URL di reindirizzamento, un parametro di query denominato code passa il codice di autorizzazione:

https://YourServer.com/?code=<authorization_code>&api_access_point=https://api.adobesign.com&web_access_point=https://secure.adobesign.com

La pubblicazione di questo codice sul server Adobe Sign insieme all’ID client e al segreto client fornisce un token di accesso per accedere al servizio. Salvare i valori nei parametri api_access_point e web_access_point. Questi valori vengono utilizzati per ulteriori richieste.

var requestURL = ' ${api_access_point}oauth/token?code=${code}'
  +'&client_id=${client_id}'
  +'&client_secret=${client_secret}&'
  +'redirect_uri=${redirect_url}&'
  +'grant_type=authorization_code';
request.post(requestURL, {form: { }
}, (err,response,body)=>{
    var token_response = JSON.parse(body)
    var access_token = token_response.access_token;
    console.log(access_token);
});

Quando un documento richiede una firma, è necessario prima caricarlo. L’applicazione può caricare il documento in api_access_point valore ricevuto durante la richiesta del token OAUTH. L'endpoint è /api/rest/v6/transientDocuments. I dati della richiesta hanno un aspetto simile al seguente:

POST /api/rest/v6/transientDocuments HTTP/1.1
Host: api.na1.adobesign.com
Authorization: Bearer MvyABjNotARealTokenHkYyi
Content-Type: multipart/form-data
Content-Disposition: form-data; name=";File"; filename="MyPDF.pdf"
<PDF CONTENT>

All’interno dell’applicazione, genera la richiesta con il codice seguente:

var uploadRequest = {
  'method': 'POST',
  'url': '${oauthParameters.signin_domain}/api/rest/v6/transientDocuments',
  'headers': {
    'Authorization': 'Bearer  ${auth_token}'
  },
  formData: {
    'File': {
      'value': fs.createReadStream(documentPath),
      'options': {
        'filename': fileName,
        'contentType': null
      }
    }
  }
};

request(uploadRequest, (error, response) => {
  if (error) throw new Error(error);
  var jsonResponse = JSON.parse(response.body);
  var transientDocumentId = jsonResponse.transientDocumentId;
  logger.info('transientDocumentId:', transientDocumentId)
});

La richiesta restituisce un transientID valore. Il documento è stato caricato, ma non è ancora stato inviato. Per inviare il documento, utilizzare il transientID per richiedere l’invio del documento.

Inizia creando un oggetto JSON contenente le informazioni per il documento da firmare. Di seguito viene riportata la variabile transientDocumentId contiene l’ID dal codice precedente e agreementDescription contiene una descrizione dell’accordo da firmare. Le persone che firmeranno il documento sono elencate in participantSetsInfo per indirizzo e-mail e ruolo.

var requestBody = {
  "fileInfos":[
    {"transientDocumentId":transientDocumentId}],
    "name":agreementDescription,
    "participantSetsInfo":[
      {"memberInfos":[{"email":"user@domain.com"}],
       "order":1,"role":"SIGNER"}
    ],
    "signatureType":"ESIGN","state":"IN_PROCESS"
};

L’invio di questa richiesta Web crea la richiesta di firma e restituisce un oggetto JSON con un ID per la richiesta di accordo:

request(requestBody, function (error, response) {
  if (error) throw new Error(error);
  var JSONResponse = JSON.parse(response.body);
  var requestId = JSONResponse.id;
});

Se i firmatari dimenticano di firmare e hanno bisogno di un’altra e-mail di notifica, invia nuovamente le notifiche utilizzando l’ID ricevuto in precedenza. L’unica differenza è che devi aggiungere anche gli ID partecipanti delle parti. Puoi ottenere gli ID dei partecipanti inviando una richiesta di GET a /agreements/{agreementID}/members.

Per richiedere l’invio del promemoria, crea prima un oggetto JSON che descriva la richiesta. L’oggetto minimo richiede un elenco degli ID partecipanti e uno stato per il promemoria ("ATTIVO", "COMPLETO" o "ANNULLATO").

La richiesta può facoltativamente contenere informazioni aggiuntive, ad esempio un valore per "nota" che verrà visualizzato all'utente. Oppure, un ritardo (in ore) nell’attesa dell’invio del promemoria (nel firstReminderDelay) e una frequenza promemoria (nel campo "frequency"), che accetta valori come DAILY_Until_SIGNED, EVERY_THIRD_DAY_Until_SIGNED o WEEKLY_Until_SIGNED.

var requestBody = {
  //participantList is an array of participant ID strings
  "recipientParticipantIds":participantList
  ,"status":"ACTIVE",
  "note":"This is a reminder to sign out important agreement."
}

var reminderRequest = {
  'method': 'POST',
  'url': '${oauthParameters.signin_domain}/api/rest/v6/agreements/${agreementID}/reminders',
  'headers': {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(requestBody)

};

request(reminderRequest, function (error, response) {
});

È tutto ciò che serve per inviare una richiesta di promemoria.

Creazione di moduli Web

Per creare moduli Web, puoi anche utilizzare l’API di Adobe Sign. I moduli Web consentono di incorporare un modulo in una pagina Web o di collegarlo direttamente a essa. Una volta creato, un modulo Web viene visualizzato anche tra i moduli Web nella console di Adobe Sign. È possibile creare moduli Web con stato BOZZA per la compilazione incrementale, stato AUTHORING per la modifica dei campi del modulo Web e stato ACTIVE per ospitare immediatamente il modulo.

Per creare un modulo Web, utilizza il modulo transientDocumentId. Stabilire un titolo per il modulo e uno stato per inizializzarlo.

var requestBody = {
  "fileInfos": [
    {
      "transientDocumentId": transientDocumentId
    }
  ],
  "name": webFormTitle,
  "state": status,
  "widgetParticipantSetInfo": {
    "memberInfos": [ { "email": "" } ],
    "role": "SIGNER"
  }
}

var createWebFormRequest = {
  'method': 'POST',
  'url': `${oauthParameters.signin_domain}/api/rest/v6/widgets`,
  'headers': {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(requestBody)
}

request(createWebFormRequest, function (error, response) {
  var jsonResp = JSON.parse(response.body);
  var webFormID = jsonResp.id;
});

Ora potete incorporare o collegare il vostro documento.

Fasi seguenti

Come si può vedere dal rapido avvio e dal codice fornito, è facile implementare i processi di approvazione dei documenti digitali e PDF utilizzando Nodo con il Adobe Acrobat Services API. Le API di Adobe si integrano perfettamente nelle applicazioni client esistenti.

Per individuare gli ambiti necessari per una chiamata o per vedere come viene creata la chiamata, è possibile creare chiamate di esempio dal Documentazione delle API REST. La QuickStart dimostrerà anche altre funzionalità e formati di file Adobe Acrobat Services Processi API.

Puoi aggiungere numerose funzionalità di PDF alle tue applicazioni, consentendo agli utenti di visualizzare e firmare in modo facile e veloce i documenti e molto altro ancora. Per iniziare, controlla Adobe Acrobat Services oggi.